skyhelper-networth
Version:
SkyHelper's Networth Calculation for Hypixel SkyBlock
232 lines (163 loc) • 8.33 kB
Markdown
# SkyHelper-Networth
[](https://discord.com/invite/fd4Be4W)
[](LICENSE)
[](https://npmjs.com/package/skyhelper-networth)
[](https://npmjs.com/package/skyhelper-networth)
[SkyHelper](https://skyhelper.altpapier.dev/)'s Networth Calculation as a Node.js module to calculate a player's SkyBlock networth by using their profile data provided by the [Hypixel API](https://api.hypixel.net/).
## Installation
```bash
npm install skyhelper-networth
```
---
## Core Concepts
### 📦 Key Classes
- **`ProfileNetworthCalculator`**: Handles networth calculation for player's profile.
- **`GenericItemNetworthCalculator`**: Calculates networth for individual items.
- **`NetworthManager`**: Central class for managing networth calculations ([singleton](https://en.wikipedia.org/wiki/Singleton_pattern)).
- **`UpdateManager`**: Manages periodic updates for items, prices and the networth package itself ([singleton](https://en.wikipedia.org/wiki/Singleton_pattern)).
### 📄 Core Interfaces
- **`NetworthOptions`**: Configuration for networth calculations
- **`NetworthResult`**: Result structure for networth calculations
- **`Item`**: Detailed representation of an in-game item
---
## Quick Start
```typescript
import { ProfileNetworthCalculator } from 'skyhelper-networth';
// Prepare input data
const profile = // https://api.hypixel.net/#tag/SkyBlock/paths/~1v2~1skyblock~1profile/get - profile.members[uuid]
const museumData = // https://api.hypixel.net/v2/skyblock/museum - museum.members[uuid]
const bankBalance = profile.banking.balance;
const profileData = profile.members[uid];
// Initialize the NetworthManager
const networthManager = new ProfileNetworthCalculator(profileData, museumData, bankBalance);
// Calculate profile networth
const networth = await networthManager.getNetworth();
console.log(networth);
```
The data structure of the output from `getNetworth` can be found at [Type Definitions](#type-definitions) section.
---
## Class Documentation
### 📊 ProfileNetworthCalculator
**Handles player profile calculations**
#### Creation
```typescript
new ProfileNetworthCalculator(profileData: object, museumData?: object, bankBalance?: number)
fromPreParsed(profileData: object, items: Items, bankBalance: number): ProfileNetworthCalculator;
```
#### Calculation Methods
```typescript
getNetworth(options?: NetworthOptions): Promise<NetworthResult>
getNonCosmeticNetworth(options?: NetworthOptions): Promise<NetworthResult>
```
#### Example Usage
```typescript
const networthManager = new ProfileNetworthCalculator(profileData, museumData, bankBalance);
const networth = await networthManager.getNonCosmeticNetworth({ prices: customPrices });
console.log(networth.types.inventory.total); // Total value of player's inventory
const nonCosmeticNetworth = await networthManager.getNonCosmeticNetworth();
console.log(nonCosmeticNetworth.networth); // Total value of player's non-cosmetic items
```
---
### 🔍 ItemNetworthCalculator
**Item-specific calculation**
#### Constructor
```typescript
new ItemNetworthCalculator(item: object)
```
#### Methods
```typescript
getNetworth(options?: NetworthOptions): Promise<Item>
getNonCosmeticNetworth(options?: NetworthOptions): Promise<Item>
```
#### Example
```typescript
const itemCalculator = new ItemNetworthCalculator(item);
const itemValue = await itemCalculator.getNetworth({ prices: newPrices });
console.log(itemValue.price); // Item's calculated value
```
---
### 🧰 NetworthManager
**Manages global configuration and item caching**
#### Constructor
```typescript
new NetworthManager(options?: NetworthManagerOptions)
```
#### Configuration Options
##### Each option can be set and obtained using the corresponding `set` and `get` methods.
| Method | Property | Type | Default | Description |
| ---------------------- | ----------------- | --------- | ---------------- | ---------------------------------------------------------------------------------- |
| `setCachePrices()` | `cachePrices` | `boolean` | `true` | Whether to cache the prices for time after fetching them or fetch them every time. |
| `setPricesRetries()` | `cachePricesTime` | `number` | `300000` (5m) | The amount of time to cache the prices in milliseconds. |
| `setCachePricesTime()` | `pricesRetries` | `number` | `3` | The amount of retries to fetch the prices when failing to fetch them. |
| `setItemsRetries()` | `itemsRetries` | `number` | `3` | The amount of retries to fetch the items when failing to fetch them. |
| `setItemsInterval()` | `itemsInterval` | `number` | `43200000` (12h) | The interval to fetch the items from the Hypixel API in milliseconds. |
| `setOnlyNetworth()` | `onlyNetworth` | `boolean` | `false` | Whether to only return the total networth or the items as well. |
| `setSortItems()` | `sortItems` | `boolean` | `true` | Whether to sort items by price. |
| `setStackItems()` | `stackItems` | `boolean` | `true` | Whether to stack items with the same name and price. |
| `setIncludeItemData()` | `includeItemData` | `boolean` | `false` | Whether to include the item data as a property in the item object. |
---
## Additional Features
### Price Management
```typescript
import { getPrices } from 'skyhelper-networth';
// Get latest prices with caching
const prices = await getPrices(true);
// Manual cache refresh
networthManager.setCachePrices(false);
```
### Update Management
```typescript
const updateManager = new UpdateManager();
updateManager.setInterval(300000); // Check updates every 5m
updateManager.disable(); // Stop automatic checks
```
---
## Type Definitions
### 📜 NetworthOptions
| Property | Type | Default | Description |
| ----------------- | --------- | -------- | ---------------------------------------------------------------------------------- |
| `prices` | `object` | `Prices` | A prices object that includes item prices. |
| `cachePrices` | `boolean` | `true` | Whether to cache the prices for time after fetching them or fetch them every time. |
| `pricesRetries` | `number` | `3` | The amount of retries to fetch the prices when failing to fetch them. |
| `onlyNetworth` | `boolean` | `false` | Whether to only return the total networth or the items as well. |
| `includeItemData` | `boolean` | `false` | Whether to include the item data as a property in the item object. |
| `sortItems` | `boolean` | `true` | Whether to sort items by price. |
| `stackItems` | `boolean` | `true` | Whether to stack items with the same name and price. |
### 📜 NetworthResult
```typescript
interface NetworthResult {
networth: number;
unsoulboundNetworth: number;
noInventory: boolean;
isNonCosmetic: boolean;
personalBank: number;
purse: number;
bank: number;
types: Record<InventoryType, Inventory>;
}
type InventoryType = 'armor' | 'equipment' | 'wardrobe' | ...;
type Inventory = {
total: number;
unsoulboundTotal: number;
items: Array<Item>;
};
```
### 📦 Item Structure
```typescript
interface Item {
name: string;
price: number;
soulbound: boolean;
cosmetic: boolean;
calculation: Calculation[];
// ... additional properties
}
```
---
## Contribution
Contributions welcome! Please follow the project's code style and add tests for new features.
```bash
git clone https://github.com/Altpapier/SkyHelper-Networth.git
npm install
npm test
```