hive-bedrock-api 2.1.11 → 3.0.0-alpha.2

package/README.md

@@ -2,6 +2,9 @@
 
 An API wrapper for the Hive Minecraft Bedrock Edition server. Which allows you to get stats for leaderboards, players, cosmetics, unique player counts, maps and metadata.
 
+> [!NOTE]
+> This API responses returnded from this package will differ from the responses returned by the offical Hive API. This due to our preference and needs when using this package on [Hive Backpack](https://hivebackpack.com).
+
 ## Getting started
 
 ```bash
@@ -9,128 +12,105 @@ $ npm install hive-bedrock-api
 $ yarn add hive-bedrock-api
 ```
 
+You should also include `hive-bedrock-data` as it includes useful functions and game information.
+
 ## Usage
 
-See [API.md](docs/API.md) for detailed documentation.
-
-### Fetch Player Infomation
+To start using this API wrapper you may construct the main class `HiveAPI`. This class can take in seperate options that will be used in every http request.
 
 ```ts
-import { getPlayerInformation } from "hive-bedrock-api";
-
-// Returns player, cosmetics, server statistics and profile infomation
-const { data, error } = await getPlayerInformation("player");
+const api = new HiveAPI({
+    resolveDynamicTitles: true,
+    apiBaseEndpoint: "https://api.playhive.com/v0",
+    requestInit: { headers: {} },
+});
 ```
 
-### Fetch All-Time Player Statistics
+### Fetch Player Infomation
 
 ```ts
-import { getAllTimeStatistics, Game } from "hive-bedrock-api";
-
-// Returns all games
-const { data, error } = await getAllTimeStats("player");
-
-// Returns a single game
-const { data, error } = await getAllTimeStats("player", Game.HideAndSeek);
+// Returns player, cosmetics, server statistics and profile infomation
+const { data, error, meta } = await api.getPlayer("player");
 ```
 
-### Fetch Season Player Statistics
+### Fetch Player Search
 
 ```ts
-import { getSeasonStatistics, Game } from "hive-bedrock-api";
-
-// Returns a game statistics
-const { data, error } = await getSeasonStatistics("player", Game.BedWars);
+// Returns a list of players matching the prefix
+const { data, error, meta } = await api.getPlayerSearch("prefix");
 ```
 
-### Fetch Monthly Player Statistics
+### Fetch All-Time/Monthly Player Statistics
 
 ```ts
-import { getMonthlyStatistics, Game } from "hive-bedrock-api";
-
-// Returns all games
-const { data, error } = await getMonthlyStats("player");
+import { Timeframe, Game } from "hive-bedrock-data";
 
-// Returns a single game
-const { data, error } = await getMonthlyStats("player", Game.BlockDrop);
+// Returns all all-time games
+const { data, error, meta } = await api.getStatistics("player", Timeframe.AllTime);
+// Returns all monthly games
+const { data, error, meta } = await api.getStatistics("player", Timeframe.Monthly);
 
-// Returns a single game in a previous month (can return muliple games)
-const { data, error } = await getMonthlyStats("player", Game.BlockDrop, {
-    year: 2023,
-    month: 1, // January
-});
+// Add in options a game to return a single game
+const { data, error, meta } = await api.getStatistics("player", Timeframe.AllTime, { game: Game.BedWars });
 ```
 
-### Fetch All-Time Leaderboard
+### Fetch Seasonal Player Statistics
 
 ```ts
-import { getAllTimeLeaderboard, Game } from "hive-bedrock-api";
+import { Game } from "hive-bedrock-data";
 
-// Returns a single game
-const { data, error } = await getAllTimeLeaderboard(Game.TreasureWars);
+// Returns seasonal statistics for a game
+const { data, error, meta } = await api.getSeasonalStatistics("player", Game.BedWars, 1);
 ```
 
-### Fetch Season Leaderboard
+### Fetch All-Time/Monthly Leaderboard
 
 ```ts
-import { getSeasonLeaderboard, Game } from "hive-bedrock-api";
+import { Timeframe, Game } from "hive-bedrock-data";
+
+// Returns all-time leaderboard
+const { data, error, meta } = await api.getLeaderboard(Timeframe.AllTime, Game.SkyWars);
+// Returns monthly leaderboard
+const { data, error, meta } = await api.getLeaderboard(Timeframe.Monthly, Game.SkyWars);
 
-// Returns a single game
-const { data, error } = await getSeasonLeaderboard(Game.BedWars);
+// Add in options the month and year for a specific leaderboard
+const { data, error, meta } = await api.getLeaderboard(Timeframe.Monthly, { month: 11, year: 2024 });
 ```
 
-### Fetch Monthly Leaderboard
+### Fetch Seasonal Leaderboard
 
 ```ts
-import { getMonthlyLeaderboard, Game } from "hive-bedrock-api";
+import { Game } from "hive-bedrock-data";
 
-// Returns a single game
-const { data, error } = await getMonthlyLeaderboard(Game.TreasureWars);
-
-// Returns a single game from a previous month
-const { data, error } = await getMonthlyLeaderboard(Game.BlockParty, {
-    year: 2023,
-    month: 11, // November
-    amount: 50,
-    skip: 20, // Sum of skip and amount must be <=100
-});
+// Returns seasonal leaderboard for a game
+const { data, error, meta } = await api.getSeasonalLeaderboard(Game.BedWars, 1);
 ```
 
 ### Fetch Global Statistics
 
 ```ts
-import { getGlobalStatistics } from "hive-bedrock-api";
-
 // Returns unqiue total player counts for different games
-const { data, error } = await getGlobalStatistics();
+const { data, error, meta } = await api.getGlobalStatistics();
 ```
 
 ### Fetch Maps
 
 ```ts
-import { getMaps, Game } from "hive-bedrock-api";
+import { Game } from "hive-bedrock-data";
 
 // Returns data for a specific game's currently active maps
-const { data, error } = await getMaps(Game.TreasureWars);
+const { data, error, meta } = await api.getGameMaps(Game.TreasureWars);
 ```
 
 ### Fetch Metadata
 
 ```ts
-import { getMetadata, Game } from "hive-bedrock-api";
+import { Game } from "hive-bedrock-data";
 
 // Returns data for a specific game's currently active maps
-const { data, error } = await getMetadata(Game.TreasureWars);
+const { data, error, meta } = await api.getGameMetadata(Game.TreasureWars);
 ```
 
-## API Response Changes
-
-Different API responses are edited by the wrapper to provide more data:
-
--   Game responses have a new value "id" showing the parent game
--   A new value for "losses" is provided
--   A new value for "kdr" is provided
--   "xp" is converted and a "level" is provided
--   "total_ratings" for just build is provided
+## Documentation
 
-See [API.md](docs/API.md#game-statistics-types) for specific fields and their corresponding types per game.
+More documentation will be added about what is returned when using this package.

package/lib/index.d.ts

@@ -1,14 +1,95 @@
-import getAllTimeLeaderboard from "./methods/getAllTimeLeaderboard";
-import getAllTimeStatistics from "./methods/getAllTimeStatistics";
-import getGlobalStatistics from "./methods/getGlobalStatistics";
-import getMaps from "./methods/getMaps";
-import getMetdata from "./methods/getMetadata";
-import getMonthlyLeaderboard from "./methods/getMonthlyLeaderboard";
-import getMonthlyStatistics from "./methods/getMonthlyStatistics";
-import getPlayerInfomation from "./methods/getPlayerInfomation";
-import getSeasonLeaderboard from "./methods/getSeasonLeaderboard";
-import getSeasonStatistics from "./methods/getSeasonStatistics";
-export { getAllTimeLeaderboard, getMonthlyLeaderboard, getAllTimeStatistics, getMonthlyStatistics, getGlobalStatistics, getMaps, getMetdata, getPlayerInfomation, getSeasonLeaderboard, getSeasonStatistics, };
-export { Game } from "hive-bedrock-data";
-export type * from "./types/output";
-export * from "./processors/index";
+import { Game, Timeframe } from "hive-bedrock-data";
+import { MethodResponse } from "./utils";
+import { ProcessedPlayerResponse } from "./processors/player";
+import { ProcessedGlobalStatisticsResponse } from "./processors/global_statistics";
+import { ProcessedMapResponse } from "./processors/map";
+import { ProcessedGameMetadata } from "./processors/meta";
+import { ProcessedPlayerSearchResponse } from "./processors/player_search";
+import { ProcessedAllGamesResponse, ProcessedGame } from "./processors/game";
+interface Options {
+    resolveDynamicTitles?: boolean;
+    apiBaseEndpoint?: string;
+    requestInit?: RequestInit;
+}
+export default class HiveAPI {
+    options: Options;
+    constructor(options?: Options);
+    private _fetchAPI;
+    /**
+     * `/game/all/main/{identifier}` Gets information about a player
+     * @param identifier Username or UUID of the player
+     * @returns The player information
+     */
+    getPlayer(identifier: string): Promise<MethodResponse<ProcessedPlayerResponse>>;
+    /**
+     * `/player/search/{prefix}` Gets a list of players that match the prefix
+     * @param prefix The prefix to search for (must be at least 4 characters long)
+     * @returns A list of players that match the prefix
+     */
+    getPlayerSearch(prefix: string): Promise<MethodResponse<ProcessedPlayerSearchResponse>>;
+    /**
+     * Gets statistics for a player
+     * @param identifier Username or UUID of the player
+     * @param timeframe The timeframe to get the statistics for
+     * @param options Additional options including specific game, month, and year
+     * @returns The player statistics
+     */
+    getStatistics(identifier: string, timeframe: Timeframe.AllTime): Promise<MethodResponse<ProcessedAllGamesResponse>>;
+    getStatistics<G extends Game>(identifier: string, timeframe: Timeframe.AllTime, options: {
+        game: G;
+    }): Promise<MethodResponse<ProcessedGame<Timeframe.AllTime, false>[G]>>;
+    getStatistics(identifier: string, timeframe: Timeframe.Monthly, options?: {
+        month?: number;
+        year?: number;
+    }): Promise<MethodResponse<ProcessedAllGamesResponse>>;
+    getStatistics<G extends Game>(identifier: string, timeframe: Timeframe.Monthly, options: {
+        game: G;
+        month?: number;
+        year?: number;
+    }): Promise<MethodResponse<ProcessedGame<Timeframe.AllTime, false>[G]>>;
+    private _getStatisticsAllTime;
+    private _getStatisticsMonthly;
+    /**
+     * `/game/season/player/{game}/{player}/{season}` Gets seasonal statistics for a player
+     * @param identifier Username or UUID of the player
+     * @param game The game to get the statistics for
+     * @param season The season to get the statistics for
+     * @returns The player's seasonal statistics
+     */
+    getSeasonalStatistics<G extends Game>(identifier: string, game: G, season?: number): Promise<MethodResponse<ProcessedGame<Timeframe.Monthly, true>[G] | null>>;
+    /**
+     * `/game/all/{game}` Gets statistics for a game
+     * @param timeframe The timeframe to get the statistics for
+     * @param game The game to get the statistics for
+     * @param options Additional options including specific month and year
+     */
+    getLeaderboard<G extends Game>(timeframe: Timeframe.AllTime, game: G): Promise<MethodResponse<ProcessedGame<Timeframe.AllTime, true>[G][] | null>>;
+    getLeaderboard<G extends Game>(timeframe: Timeframe.Monthly, game: G): Promise<MethodResponse<ProcessedGame<Timeframe.Monthly, true>[G][] | null>>;
+    private _getLeaderboardAllTime;
+    private _getLeaderboardMonthly;
+    /**
+     * `/game/season/{game}/{season}` Gets seasonal statistics for a game
+     * @param game The game to get the statistics for
+     * @param season The season to get the statistics for
+     * @returns The seasonal statistics for the game
+     */
+    getSeasonalLeaderboard<G extends Game>(game: G, season?: number): Promise<MethodResponse<ProcessedGame<Timeframe.Monthly, true>[G][]>>;
+    /**
+     * `/global/statistics` Gets global statistics
+     * @returns The global statistics
+     */
+    getGlobalStatistics(): Promise<MethodResponse<ProcessedGlobalStatisticsResponse>>;
+    /**
+     * `/game/map/{game}` Gets information about the maps in a game
+     * @param game The game to get the maps for (fails for games without maps)
+     * @returns A list of maps in the game
+     */
+    getGameMaps(game: Game): Promise<MethodResponse<ProcessedMapResponse>>;
+    /**
+     * `/game/meta/{game}` Gets metadata about a game
+     * @param game The game to get the metadata for
+     * @returns The metadata for the game
+     */
+    getGameMetadata(game: Game): Promise<MethodResponse<ProcessedGameMetadata>>;
+}
+export {};