@zikeji/hypixel
Version:
With IntelliSense support & test coverage, this is an unopinionated async/await API wrapper for Hypixel's Public API. It is developed in TypeScript complete with documentation, typed interfaces for all API responses, built-in rate-limit handling, flexible
235 lines (234 loc) • 7.81 kB
TypeScript
import { Guild } from "./methods/guild";
import { Player } from "./methods/player";
import { Recentgames } from "./methods/recentGames";
import { Resources } from "./methods/resources";
import { SkyBlock } from "./methods/skyblock";
import { Status } from "./methods/status";
import { ResultObject } from "./util/ResultObject";
import type { BoostersResponse, CountsResponse, LeaderboardsResponse, PunishmentStatsResponse } from "./types/AugmentedTypes";
import type { DefaultMeta } from "./types/DefaultMeta";
import { Housing } from "./methods/housing";
/**
* Rate limit data returned in the meta property of API responses.
*/
export interface RateLimitData {
/**
* Remaining API calls until the limit resets.
*/
remaining: number;
/**
* Time, in seconds, until remaining resets to limit.
*/
reset: number;
/**
* How many requests per minute your API key can make.
*/
limit: number;
}
/** @hidden */
export interface RequestOptions {
url: string;
timeout: number;
userAgent: string;
noRateLimit: boolean;
getRateLimitHeaders: Client["getRateLimitHeaders"];
}
/** @hidden */
export interface Parameters {
[parameter: string]: string;
}
/**
* If you want built in caching, implementing these methods (or utilitizing an library that includes these methods) is a must. Refer to the [cache](https://node-hypixel.zikeji.com/guide/cache) guide.
*/
export interface BasicCache {
get<T>(key: string): Promise<(T & DefaultMeta) | undefined>;
set<T>(key: string, value: T & DefaultMeta): Promise<void>;
}
export interface ClientOptions {
/**
* Amount of times to retry a failed request.
* @default 3
*/
retries?: number;
/**
* The time, in milliseconds, you want to wait before giving up on the method call.
* @default 10000
*/
timeout?: number;
/**
* User agent the client uses when making calls to Hypixel's API
* @default @zikeji/hypixel
*/
userAgent?: string;
/**
* Functions you want to use for caching results. Optional.
*/
cache?: BasicCache;
}
export declare interface Client {
/**
* Listen to the "limited" event which emits when the client starts limiting your calls due to hitting the rate limit.
* @category Events
*/
on(event: "limited", listener: (limit: number, reset: Date) => void): this;
/**
* Listen to the "reset" event which emits when the API rate limit resets.
* @category Events
*/
on(event: "reset", listener: () => void): this;
/**
* Listen once to the "limited" event which emits when the client starts limiting your calls due to hitting the rate limit.
* @category Events
*/
once(event: "limited", listener: (limit: number, reset: Date) => void): this;
/**
* Listen once to the "reset" event which emits when the API rate limit resets.
* @category Events
*/
once(event: "reset", listener: () => void): this;
/**
* Remove your function listening to the "limited" event.
* @category Events
*/
off(event: "limited", listener: () => void): this;
/**
* Remove your function listening to the "reset" event.
* @category Events
*/
off(event: "reset", listener: () => void): this;
}
/**
* The main API client, instantiate it with your API key.
* @example
* ```typescript
* import { Client as HypixelClient } from "@zikeji/hypixel";
* const client = new HypixelClient("legit-api-key-heye");
* ```
* @category Client
*/
export declare class Client {
/**
* Create a new instance of the API client.
* @param key Your Hypixel API key.
* @param options Any options and customizations being applied.
*/
constructor(key: string, options?: ClientOptions);
/**
* Returns list of boosters.
* @example
* ```typescript
* const boosters = await client.boosters();
* console.log(boosters);
* ```
* @category API
*/
boosters(): Promise<ResultObject<BoostersResponse, ["success"]>>;
/**
* Returns the current player count along with the player count of each public game + mode on the server.
* @example
* ```typescript
* const response = await client.counts();
* console.log(response);
* ```
* @category API
*/
counts(): Promise<ResultObject<CountsResponse, ["success"]>>;
/**
* Returns the guild by the requested ID if found.
* @example
* ```typescript
* const guild = await client.guild.id("553490650cf26f12ae5bac8f");
* ```
* @category API
*/
guild: Guild;
/**
* Return's housing data, such as active public houses.
* @example
* ```typescript
* const housingData = await client.housing.active();
* console.log(housingData);
* ```
* @category API
*/
housing: Housing;
/**
* Returns a list of the official leaderboards and their current standings for games on the network.
* @example
* ```typescript
* const leaderboards = await client.leaderboards();
* console.log(leaderboards);
* ```
* @category API
*/
leaderboards(): Promise<ResultObject<LeaderboardsResponse, ["leaderboards"]>>;
/**
* Returns a player's data, such as game stats.
* @example
* ```typescript
* const player = await client.player.uuid("20934ef9488c465180a78f861586b4cf");
* console.log(player);
* ```
* @category API
*/
player: Player;
/**
* Returns some statistics about punishments.
* @example
* ```typescript
* const response = await client.punishmentstats();
* console.log(response);
* ```
* @category API
*/
punishmentstats(): Promise<ResultObject<PunishmentStatsResponse, ["success"]>>;
/**
* Returns recent games of a player. A maximum of 100 games are returned and recent games are only stored for up to 3 days at this time.
* @example
* ```typescript
* const response = await client.recentgames.uuid("20934ef9488c465180a78f861586b4cf");
* console.log(response);
* ```
* @category API
*/
recentgames: Recentgames;
/**
* Relatively static Hypixel resources that don't change often at all.
* @category API
*/
resources: Resources;
/**
* All SkyBlock related endpoints.
* @category API
*/
skyblock: SkyBlock;
/**
* Returns online status information for given player, including game, mode and map when available.
* @example
* ```typescript
* const response = await client.status.uuid("20934ef9488c465180a78f861586b4cf");
* console.log(response);
* ```
* @category API
*/
status: Status;
/**
* The raw query method used by this library. You may use this if you need to use an undocumented method with this library.
*
* @category Custom
* @param path The path on the method you want to query.
* @param parameters Any search parameters you want to use.
* @typeParam T As all of Hypixel's API methods return a basic `{ success: boolean; cause?: string; }`, this type parameter (if using Typescript) extends an interface including those.
* @example
* Getting the ID of a guild using the [findGuild](https://github.com/HypixelDev/PublicAPI/blob/master/Documentation/methods/findGuild.md) method.
* ```javascript
* const response = await client.call("findGuild", { byName: "Mini Squid" });
* console.log(response);
* // { success: true, guild: '553490650cf26f12ae5bac8f' }
* ```
*/
call<T extends Record<string, unknown>>(path: string, parameters?: Parameters): Promise<T & DefaultMeta & {
cached?: boolean;
}>;
}
export default Client;