mcutils-js-api 2.0.36 → 2.0.38

package/dist/index.d.ts

@@ -10,9 +10,19 @@ import { CachedPlayerName } from "./types/cache/cached-player-name";
 import { StatisticsResponse } from "./types/response/statistics-response";
 import { Skin } from "./types/player/skin/skin";
 import { Page } from "./types/pagination/pagination";
+import { PlayerSearchEntry } from "./types/player/player-search-entry";
 export declare class McUtilsAPI {
     private readonly endpoint;
-    constructor(endpoint?: string);
+    private readonly fetchOptions?;
+    constructor(endpoint?: string, fetchOptions?: RequestInit);
+    /**
+     * Requests data from the API.
+     *
+     * @param path the path to the API endpoint
+     * @param options the options for the request
+     * @returns the data or the error (if one occurred)
+     */
+    private request;
     /**
      * Build URL search params string from a record of key-value pairs.
      *
@@ -196,5 +206,15 @@ export declare class McUtilsAPI {
         skins?: Page<Skin>;
         error?: ErrorResponse;
     }>;
+    /**
+     * Search for players by username.
+     *
+     * @param query the query to search for (eg: aetheria)
+     * @returns the player search entry or the error (if one occurred)
+     */
+    searchPlayers(query: string): Promise<{
+        entry?: PlayerSearchEntry;
+        error?: ErrorResponse;
+    }>;
 }
 export default McUtilsAPI;

package/dist/index.js

@@ -1,6 +1,24 @@
 export class McUtilsAPI {
-    constructor(endpoint = "https://mc.fascinated.cc/api") {
+    constructor(endpoint = "https://mc.fascinated.cc/api", fetchOptions) {
         this.endpoint = endpoint;
+        this.fetchOptions = fetchOptions;
+    }
+    /**
+     * Requests data from the API.
+     *
+     * @param path the path to the API endpoint
+     * @param options the options for the request
+     * @returns the data or the error (if one occurred)
+     */
+    async request(path, options) {
+        const { responseType = "json", ...init } = options ?? {};
+        const url = path.startsWith("http") ? path : `${this.endpoint}${path}`;
+        const response = await fetch(url, { ...this.fetchOptions, ...init });
+        if (!response.ok) {
+            return { error: (await response.json()) };
+        }
+        const data = responseType === "arrayBuffer" ? await response.arrayBuffer() : await response.json();
+        return { data: data };
     }
     /**
      * Build URL search params string from a record of key-value pairs.
@@ -20,15 +38,8 @@ export class McUtilsAPI {
      * @returns the server or the error (if one occurred)
      */
     async fetchServer(host, type) {
-        const response = await fetch(`${this.endpoint}/servers/${type}/${host}`);
-        if (response.ok) {
-            return {
-                server: (await response.json()),
-            };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/servers/${type}/${host}`);
+        return error ? { error } : { server: data };
     }
     /**
      * Fetch a Java Minecraft server.
@@ -37,15 +48,8 @@ export class McUtilsAPI {
      * @returns the server or the error (if one occurred)
      */
     async fetchJavaServer(host) {
-        const response = await fetch(`${this.endpoint}/servers/java/${host}`);
-        if (response.ok) {
-            return {
-                server: (await response.json()),
-            };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/servers/java/${host}`);
+        return error ? { error } : { server: data };
     }
     /**
      * Fetch a Bedrock Minecraft server.
@@ -54,15 +58,8 @@ export class McUtilsAPI {
      * @returns the server or the error (if one occurred)
      */
     async fetchBedrockServer(host) {
-        const response = await fetch(`${this.endpoint}/servers/bedrock/${host}`);
-        if (response.ok) {
-            return {
-                server: (await response.json()),
-            };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/servers/bedrock/${host}`);
+        return error ? { error } : { server: data };
     }
     /**
      * Fetch whether a server is blocked by Mojang.
@@ -71,14 +68,10 @@ export class McUtilsAPI {
      * @returns the blocked status or the error (if one occurred)
      */
     async fetchServerBlocked(host) {
-        const response = await fetch(`${this.endpoint}/servers/blocked/${host}`);
-        if (response.ok) {
-            const json = (await response.json());
-            return { blocked: json.blocked };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/servers/blocked/${host}`);
+        if (error)
+            return { error };
+        return { blocked: data.blocked };
     }
     /**
      * Look up IP address (geo + ASN).
@@ -87,13 +80,7 @@ export class McUtilsAPI {
      * @returns the IP lookup response or the error (if one occurred)
      */
     async fetchIpLookup(query) {
-        const response = await fetch(`${this.endpoint}/ips/${query}`);
-        if (response.ok) {
-            return { data: (await response.json()) };
-        }
-        return {
-            error: (await response.json()),
-        };
+        return this.request(`/ips/${query}`);
     }
     /**
      * Fetch a player by UUID or username.
@@ -102,15 +89,8 @@ export class McUtilsAPI {
      * @returns the player or the error (if one occurred)
      */
     async fetchPlayer(id) {
-        const response = await fetch(`${this.endpoint}/players/${id}`);
-        if (response.ok) {
-            return {
-                player: (await response.json()),
-            };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/players/${id}`);
+        return error ? { error } : { player: data };
     }
     /**
      * Resolve a username to UUID (or UUID to username).
@@ -119,15 +99,8 @@ export class McUtilsAPI {
      * @returns the player name data or the error (if one occurred)
      */
     async fetchPlayerUuid(id) {
-        const response = await fetch(`${this.endpoint}/players/uuid/${id}`);
-        if (response.ok) {
-            return {
-                playerName: (await response.json()),
-            };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/players/uuid/${id}`);
+        return error ? { error } : { playerName: data };
     }
     /**
      * Fetch a server favicon/icon image.
@@ -136,13 +109,8 @@ export class McUtilsAPI {
      * @returns the PNG image or the error (if one occurred)
      */
     async fetchServerIcon(host) {
-        const response = await fetch(`${this.endpoint}/servers/icon/${host}`);
-        if (response.ok) {
-            return { image: await response.arrayBuffer() };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/servers/icon/${host}`, { responseType: "arrayBuffer" });
+        return error ? { error } : { image: data };
     }
     /**
      * Fetch a server preview image.
@@ -153,13 +121,8 @@ export class McUtilsAPI {
      * @returns the PNG image or the error (if one occurred)
      */
     async fetchServerPreview(platform, host, size = 768) {
-        const response = await fetch(`${this.endpoint}/servers/${platform}/preview/${host}${this.buildParams({ size: String(size) })}`);
-        if (response.ok) {
-            return { image: await response.arrayBuffer() };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/servers/${platform}/preview/${host}${this.buildParams({ size: String(size) })}`, { responseType: "arrayBuffer" });
+        return error ? { error } : { image: data };
     }
     /**
      * Fetch a player's skin image.
@@ -168,13 +131,8 @@ export class McUtilsAPI {
      * @returns the skin PNG image or the error (if one occurred)
      */
     async fetchPlayerSkinTexture(id) {
-        const response = await fetch(`${this.endpoint}/skins/${id}/texture.png`);
-        if (response.ok) {
-            return { image: await response.arrayBuffer() };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/skins/${id}/texture.png`, { responseType: "arrayBuffer" });
+        return error ? { error } : { image: data };
     }
     /**
      * Fetch a specific part of a player's skin (eg: head, body).
@@ -186,13 +144,8 @@ export class McUtilsAPI {
      * @returns the skin part PNG image or the error (if one occurred)
      */
     async fetchPlayerSkin(id, part, size = 768, overlays = true) {
-        const response = await fetch(`${this.endpoint}/skins/${id}/${part}.png${this.buildParams({ size: String(size), overlays: String(overlays) })}`);
-        if (response.ok) {
-            return { image: await response.arrayBuffer() };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/skins/${id}/${part}.png${this.buildParams({ size: String(size), overlays: String(overlays) })}`, { responseType: "arrayBuffer" });
+        return error ? { error } : { image: data };
     }
     /**
      * Fetch the list of available capes (e.g. Migrator).
@@ -200,13 +153,8 @@ export class McUtilsAPI {
      * @returns the list of cape data or the error (if one occurred)
      */
     async fetchCapes() {
-        const response = await fetch(`${this.endpoint}/capes`);
-        if (response.ok) {
-            return { capes: (await response.json()) };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/capes`);
+        return error ? { error } : { capes: data };
     }
     /**
      * Fetch a cape texture image.
@@ -215,13 +163,8 @@ export class McUtilsAPI {
      * @returns the cape PNG image or the error (if one occurred)
      */
     async fetchCapeTexture(query) {
-        const response = await fetch(`${this.endpoint}/capes/${query}/texture.png`);
-        if (response.ok) {
-            return { image: await response.arrayBuffer() };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/capes/${query}/texture.png`, { responseType: "arrayBuffer" });
+        return error ? { error } : { image: data };
     }
     /**
      * Fetch a rendered cape part (e.g. front).
@@ -232,13 +175,8 @@ export class McUtilsAPI {
      * @returns the cape part PNG image or the error (if one occurred)
      */
     async fetchCapePart(query, type, size = 768) {
-        const response = await fetch(`${this.endpoint}/capes/${query}/${type}.png${this.buildParams({ size: String(size) })}`);
-        if (response.ok) {
-            return { image: await response.arrayBuffer() };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/capes/${query}/${type}.png${this.buildParams({ size: String(size) })}`, { responseType: "arrayBuffer" });
+        return error ? { error } : { image: data };
     }
     /**
      * Fetch the list of available server registry entries.
@@ -247,13 +185,8 @@ export class McUtilsAPI {
      * @returns the list of server registry entries or the error (if one occurred)
      */
     async fetchServerRegistryEntries(query) {
-        const response = await fetch(`${this.endpoint}/servers${this.buildParams({ query: query })}`);
-        if (response.ok) {
-            return { entries: (await response.json()) };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/servers${this.buildParams({ query: query })}`);
+        return error ? { error } : { entries: data };
     }
     /**
      * Fetch the statistics of the API.
@@ -261,13 +194,8 @@ export class McUtilsAPI {
      * @returns the statistics or the error (if one occurred)
      */
     async fetchStatistics() {
-        const response = await fetch(`${this.endpoint}/statistics`);
-        if (response.ok) {
-            return { statistics: (await response.json()) };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/statistics`);
+        return error ? { error } : { statistics: data };
     }
     /**
      * Fetch the list of available skins.
@@ -276,13 +204,18 @@ export class McUtilsAPI {
      * @returns the list of skins or the error (if one occurred)
      */
     async fetchSkins(page = 1) {
-        const response = await fetch(`${this.endpoint}/skins${this.buildParams({ page: String(page) })}`);
-        if (response.ok) {
-            return { skins: (await response.json()) };
-        }
-        return {
-            error: (await response.json()),
-        };
+        const { data, error } = await this.request(`/skins${this.buildParams({ page: String(page) })}`);
+        return error ? { error } : { skins: data };
+    }
+    /**
+     * Search for players by username.
+     *
+     * @param query the query to search for (eg: aetheria)
+     * @returns the player search entry or the error (if one occurred)
+     */
+    async searchPlayers(query) {
+        const { data, error } = await this.request(`/players/search/${query}`);
+        return error ? { error } : { entry: data };
     }
 }
 export default McUtilsAPI;

package/dist/types/player/player-search-entry.d.ts

@@ -0,0 +1,6 @@
+import { Skin } from "./skin/skin";
+export type PlayerSearchEntry = {
+    uuid: string;
+    username: string;
+    skin: Skin;
+};

package/dist/types/player/player-search-entry.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcutils-js-api",
-  "version": "2.0.36",
+  "version": "2.0.38",
   "module": "dist/index.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",