add skins endpoint

Author: RealFascinated

package.json

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

src/index.ts

@@ -9,6 +9,8 @@ import { ServerRegistryEntry } from "./types/server-registry/server-registry-ent
 import { Player } from "./types/player/player";
 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";
 
 export class McUtilsAPI {
   private readonly endpoint: string;
@@ -343,6 +345,22 @@ export class McUtilsAPI {
       error: (await response.json()) as ErrorResponse,
     };
   }
+
+  /**
+   * Fetch the list of available skins.
+   *
+   * @param page the page to fetch (default: 1)
+   * @returns the list of skins or the error (if one occurred)
+   */
+  async fetchSkins(page: number = 1): Promise<{ skins?: Page<Skin>; error?: ErrorResponse }> {
+    const response = await fetch(`${this.endpoint}/skins${this.buildParams({ page: String(page) })}`);
+    if (response.ok) {
+      return { skins: (await response.json()) as Page<Skin> };
+    }
+    return {
+      error: (await response.json()) as ErrorResponse,
+    };
+  }
 }
 
 export default McUtilsAPI;

src/types/pagination/pagination.ts

@@ -0,0 +1,30 @@
+/**
+ * Callback passed to a page fetcher: limit (items per page) and skip (offset).
+ */
+export type PageCallback = {
+    limit: number;
+    skip: number;
+};
+
+/**
+ * A single page of paginated results.
+ */
+export type Page<T> = {
+    items: T[];
+    totalItems: number;
+    itemsPerPage: number;
+    totalPages: number;
+};
+
+/**
+ * Pagination configuration (items per page and total count).
+ */
+export type PaginationConfig = {
+    itemsPerPage: number;
+    totalItems: number;
+};
+
+/**
+ * Fetcher used to load items for a page. Receives limit and skip via PageCallback.
+ */
+export type PageFetcher<T> = (callback: PageCallback) => T[] | Promise<T[]>;