@skyblock‑ts/toolkit

High‑level, cached and convenient utility functions for Hypixel SkyBlock
built on top of @skyblock‑ts/core.

Installation

npm install @skyblock-ts/toolkit
# or
pnpm add @skyblock-ts/toolkit
# or
yarn add @skyblock-ts/toolkit

Quick Start

import { ToolkitClient } from "@skyblock-ts/toolkit";

// You can pass your Hypixel API key (optional for cached reads):
const client = new ToolkitClient({ APIKey: "MY_KEY", batchSize: 20, cacheTTL: 300_000 });

async function main() {
  // - Auctions
  const all = await client.auctions.all();
  console.log("Total auctions:", all.length);

  const cheapSwords = await client.auctions.get({ itemName: "HYPERION", maxPrice: 1_000_000_000 });
  console.log("Cheap hyperions:", cheapSwords.length);

  const bestBin = await client.auctions.lowestBIN({ itemName: "ENCHANTED_GOLD" });
  console.log("Lowest ENCHANTED_GOLD BIN:", bestBin?.starting_bid);

  // - Profiles
  const uuid = await client.profiles.uuidForName("Notch");
  console.log("Notch’s UUID:", uuid);

  const profs = await client.profiles.listProfilesByName("Notch");
  console.log("SkyBlock profiles:", profs.map(p => p.profile_id));

  const active = await client.profiles.getActiveProfile(uuid!);
  console.log("Active profile member data:", active);

  // - Bazaar
  const bazaar = await client.bazaar.listProducts();
  console.log("Bazaar items:", Object.keys(bazaar).length);

  const gold = await client.bazaar.getProduct("ENCHANTED_GOLD");
  console.log("Enchanted Gold buy price:", gold?.buy_summary[0].pricePerUnit);

  // - Data (items, collections, skills)
  const item = await client.data.getItemById("FARM_ARMOR_CHESTPLATE");
  const skill = await client.data.getSkill("FARMING");

  // - Misc (news, election, bingo, firesales)
  const news = await client.misc.getNews();
  const firesales = await client.misc.getFiresales();

  // - Profile extras (museum, garden, bingo) — use a profile ID from getProfileById / listProfilesByUuid
  const profileId = active?.profile_id ?? "";
  const museum = await client.profiles.getMuseum(profileId);
  const bingoEvents = await client.profiles.getBingoData(uuid!);
}

main().catch(console.error);

Modules & Methods

Auctions

• all(): Promise<AuctionItem[]>
• get(filter: AuctionFilter): Promise<AuctionItem[]>
• lowestBIN(filter: AuctionFilter): Promise<AuctionItem \| null>
• lowestBINs(filters: AuctionFilter[]): Promise<Record<string, number>>
• averagePrice(filter: AuctionFilter): Promise<number>

Profiles

• uuidForName(name: string): Promise<string \| null>

• listProfilesByUuid(uuid: string): Promise<ProfileItem[]>

• listProfilesByName(name: string): Promise<ProfileItem[]>

• getProfileById(profileId: string): Promise<ProfileItem \| null>

• getActiveProfile(uuid: string): Promise<ProfileItem \| null>

• getMuseum(profileId: string): Promise<Record<string, MuseumMember> \| null>

• getGarden(profileId: string): Promise<GardenItem \| null>

• getBingoData(uuid: string): Promise<BingoEvent[]>

Bazaar

• listProducts(): Promise<Record<string, BazaarItem>>
• getProduct(key: string): Promise<BazaarItem \| null>

Data

• listItems(): Promise<ItemItem[]>
• getItemById(id: string): Promise<ItemItem \| null>
• getItemsByMaterial(material: string): Promise<ItemItem[]>
• listCollections(): Promise<Record<string, CollectionItem>>
• getCollection(id: string): Promise<CollectionItem \| null>
• listSkills(): Promise<Record<string, SkillItem>>
• getSkill(id: string): Promise<SkillItem \| null>

Misc

• getNews(): Promise<NewsItem[]> (requires API key)
• getElection(): Promise<{ mayor: Mayor; current: Election }>
• getCurrentBingoEvent(): Promise<... \| null>
• getFiresales(): Promise<FireSaleItem[]>

Cache: By default results are cached in memory for cacheTTL ms (default: 3 minutes).
Batching: Auction pages are fetched in parallel batches of batchSize (default: 10).

API Reference

Browse the full TypeScript types in dist/index.d.ts
or peek at the source under src/.

Made with ❤️ by @unloopedmido.

MIT License — see LICENSE.