osrs-tools 2.4.0 → 2.5.2

package/README.md

@@ -1,183 +1,270 @@
-
-
-Refer to modern Node Packages. Update the Package.json to ONLY need the modern dependencies, reduce packages as much as possible.
-
-
-
-
-
-# OSRS Tools
-
-[![NPM Version](https://img.shields.io/npm/v/osrs-tools.svg?style=for-the-badge)](https://www.npmjs.com/package/osrs-tools)
-[![Downloads](https://img.shields.io/npm/dm/osrs-tools.svg?style=for-the-badge)](https://www.npmjs.com/package/osrs-tools)
-[![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue.svg?style=for-the-badge)](https://www.typescriptlang.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
-[![Node Version](https://img.shields.io/node/v/osrs-tools.svg?style=for-the-badge)](https://nodejs.org)
-[![Test Coverage](https://img.shields.io/codecov/c/github/jamescer/osrs-tools.svg?style=for-the-badge)](https://codecov.io/gh/jamescer/osrs-tools)
-
-> A modern TypeScript library for Old School RuneScape (OSRS) data and utilities. Built for developers creating tools, bots, web applications, and analytics around OSRS content.
-
-📦 **Type-safe**   🚀 **Well-tested**   📚 **Documented**   🔄 **Actively maintained**
-
-## Live Demo
-
-Explore the project interactively on CodeSandbox:
-
-[![Edit on CodeSandbox](https://img.shields.io/badge/CodeSandbox-View-blue?logo=codesandbox&style=for-the-badge)](https://codesandbox.io/p/sandbox/xtgp9k)
-
----
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Examples](#examples)
-- [Development](#development)
-- [Contributing](#contributing)
-- [Support](#support)
-- [License](#license)
-
-## Installation
-
-### Prerequisites
-
-- Node.js 16.x or higher
-- TypeScript 4.9+
-
-### Package Installation
-
-```bash
-npm install osrs-tools
-```
-
-For account-related features (hiscores, stats):
-
-```bash
-npm install osrs-json-hiscores
-```
-
-## Examples
-
-### Quest System
-
-```typescript
-import { QuestTool, Quest } from 'osrs-tools';
-
-// Get quest information
-const dragonSlayer = QuestTool.getQuestByName('Dragon Slayer');
-console.log(dragonSlayer.requirements);
-
-// Check quest completion requirements
-const questTool = new QuestTool();
-questTool.setOsrsAccount(playerAccount);
-const canComplete = questTool.canCompleteQuest(dragonSlayer);
-```
-
-### Slayer System
-
-```typescript
-import { Duradel } from 'osrs-tools';
-
-// Get master's task list
-const tasks = Duradel.tasks;
-
-// Get random assignment
-const task = Duradel.getRandomTask();
-console.log(task.name); // e.g., "Abyssal demons"
-console.log(task.requirements); // Shows requirements
-```
-
-### Account Management
-
-```typescript
-import { OsrsAccount } from 'osrs-tools';
-
-// Create/load account
-const account = OsrsAccount.fromJson({
-  name: 'Player123',
-  skills: {
-    attack: { level: 60 },
-    strength: { level: 55 },
-    defence: { level: 50 },
-  },
-});
-
-// Get skill levels
-const attackLevel = account.getSkill('attack')?.level;
-```
-
-### Documentation Links
-
-- [Full API Documentation](https://github.com/jamescer/osrs-tools/wiki)
-- [Type Definitions](https://github.com/jamescer/osrs-tools/blob/master/src/model/quest/types.ts)
-- [Code Examples](https://github.com/jamescer/osrs-tools//examples)
-
-## Development
-
-### Local Setup
-
-```bash
-# Clone and setup
-git clone https://github.com/jamescer/osrs-tools.git
-cd osrs-tools
-npm install
-
-# Build and test
-npm run build
-npm test
-```
-
-### Available Scripts
-
-| Command      | Description             |
-| ------------ | ----------------------- |
-| `build`      | Build the project       |
-| `test`       | Run tests               |
-| `test:watch` | Run tests in watch mode |
-| `lint`       | Lint the code           |
-| `format`     | Format the code         |
-| `docs`       | Generate documentation  |
-
-## Contributing
-
-We welcome contributions! We use [Conventional Commits](https://www.conventionalcommits.org/).
-
-### Getting Started
-
-1. Fork and clone the repository
-2. Create a branch (`feat/amazing-feature`)
-3. Make your changes
-4. Run tests (`npm test && npm run lint`)
-5. Commit with conventional format:
-
-   ```bash
-   feat: add quest requirement validation
-   fix: correct slayer task weights
-   docs: update API documentation
-   ```
-
-6. Push and open a Pull Request
-
-### Guidelines
-
-- Add tests for new features
-- Update documentation for changes
-- Follow existing code style
-- Keep changes focused
-
-## Support
-
-Need help or want to contribute?
-
-- [Report Issues](https://github.com/jamescer/osrs-tools/issues)
-- [Request Features](https://github.com/jamescer/osrs-tools/issues)
-- [Join Discussions](https://github.com/jamescer/osrs-tools/discussions)
-
-## License
-
-[MIT](./LICENSE) © James Cerniglia
-
-## Credits
-
-- **Author**: [James Cerniglia](mailto:jamesmcerniglia@gmail.com)
-- **Contributors**: [View all contributors](https://github.com/jamescer/osrs-tools/graphs/contributors)
-- **Data Source**: [Old School RuneScape Wiki](https://oldschool.runescape.wiki/)
+
+
+Refer to modern Node Packages. Update the Package.json to ONLY need the modern dependencies, reduce packages as much as possible.
+
+
+
+
+
+# OSRS Tools
+
+[![NPM Version](https://img.shields.io/npm/v/osrs-tools.svg?style=for-the-badge)](https://www.npmjs.com/package/osrs-tools)
+[![Downloads](https://img.shields.io/npm/dm/osrs-tools.svg?style=for-the-badge)](https://www.npmjs.com/package/osrs-tools)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue.svg?style=for-the-badge)](https://www.typescriptlang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+[![Node Version](https://img.shields.io/node/v/osrs-tools.svg?style=for-the-badge)](https://nodejs.org)
+[![Test Coverage](https://img.shields.io/codecov/c/github/jamescer/osrs-tools.svg?style=for-the-badge)](https://codecov.io/gh/jamescer/osrs-tools)
+
+> A modern TypeScript library for Old School RuneScape (OSRS) data and utilities. Built for developers creating tools, bots, web applications, and analytics around OSRS content.
+
+📦 **Type-safe**   🚀 **Well-tested**   📚 **Documented**   🔄 **Actively maintained**
+
+## Live Demo
+
+Explore the project interactively on CodeSandbox:
+
+[![Edit on CodeSandbox](https://img.shields.io/badge/CodeSandbox-View-blue?logo=codesandbox&style=for-the-badge)](https://codesandbox.io/p/sandbox/xtgp9k)
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Examples](#examples)
+- [Development](#development)
+- [Contributing](#contributing)
+- [Support](#support)
+- [License](#license)
+
+## Installation
+
+### Prerequisites
+
+- Node.js 16.x or higher
+- TypeScript 4.9+
+
+### Package Installation
+
+```bash
+npm install osrs-tools
+```
+
+For account-related features (hiscores, stats):
+
+```bash
+npm install osrs-json-hiscores
+```
+
+## Examples
+
+### Core Imports (Recommended)
+
+The main `osrs-tools` export provides the most frequently used classes:
+
+```typescript
+import { 
+  QuestTool, 
+  OsrsAccount, 
+  ClueScrollHelper,
+  Item 
+} from 'osrs-tools';
+
+// Use core API directly
+const questTool = new QuestTool();
+const account = OsrsAccount.fromJson({ name: 'Player123' });
+```
+
+### Subpackage Imports (Tree-Shakeable)
+
+Import from subpackages for more granular control and better tree-shaking:
+
+```typescript
+// Quest module - access all quests and quest utilities
+import { QuestTool, DragonSlayerI } from 'osrs-tools/quest';
+
+// Slayer module - slayer masters and utilities
+import { Duradel, SlayerMaster } from 'osrs-tools/slayer';
+
+// Account & skills
+import { OsrsAccount, Skill } from 'osrs-tools/account';
+
+// Achievement diaries
+import { Ardougne, DiaryName } from 'osrs-tools/diary';
+
+// Tools & utilities
+import { ClueScrollHelper, experience } from 'osrs-tools/tools';
+import { cache, validation } from 'osrs-tools/utils';
+```
+
+### Quest System
+
+```typescript
+// Access a specific quest
+import { DragonSlayerI } from 'osrs-tools/quest';
+
+// Or get by name from QuestTool
+import { QuestTool } from 'osrs-tools';
+const dragonSlayer = QuestTool.getQuestByName('Dragon Slayer');
+console.log(dragonSlayer.requirements);
+
+// Check quest completion requirements
+const questTool = new QuestTool();
+questTool.setOsrsAccount(playerAccount);
+const canComplete = questTool.canCompleteQuest(dragonSlayer);
+```
+
+### Slayer System
+
+```typescript
+import { Duradel } from 'osrs-tools/slayer';
+
+// Get master's task list
+const tasks = Duradel.tasks;
+
+// Get random assignment
+const task = Duradel.getRandomTask();
+console.log(task.name); // e.g., "Abyssal demons"
+console.log(task.requirements); // Shows requirements
+```
+
+### Account Management
+
+```typescript
+import { OsrsAccount } from 'osrs-tools/account';
+
+// Create/load account
+const account = OsrsAccount.fromJson({
+  name: 'Player123',
+  skills: {
+    attack: { level: 60 },
+    strength: { level: 55 },
+    defence: { level: 50 },
+  },
+});
+
+// Get skill levels
+const attackLevel = account.getSkill('attack')?.level;
+```
+
+### 3D Item Models
+
+```typescript
+import { yellowPartyhatModelPath } from 'osrs-tools';
+
+console.log(yellowPartyhatModelPath);
+// "osrs-tools/models/YellowPartyhat.obj"
+```
+
+- **Node.js**: resolve the shipped asset with `require.resolve(yellowPartyhatModelPath)` and read it with `fs.readFileSync(...)`.
+- **Bundlers**: import the raw asset directly from `osrs-tools/models/YellowPartyhat.obj` or use a `?url` suffix if your bundler supports it.
+
+### Documentation Links
+
+- [Full API Documentation](https://github.com/jamescer/osrs-tools/wiki)
+- [Type Definitions](https://github.com/jamescer/osrs-tools/blob/master/src/model/quest/types.ts)
+- [Code Examples](https://github.com/jamescer/osrs-tools//examples)
+
+## Development
+
+### Local Setup
+
+```bash
+# Clone and setup
+git clone https://github.com/jamescer/osrs-tools.git
+cd osrs-tools
+npm install
+
+# Build and test
+npm run build
+npm test
+```
+
+### Available Scripts
+
+| Command         | Description                    |
+| --------------- | ------------------------------ |
+| `build`         | Compile TypeScript to dist/    |
+| `dev`           | Watch mode compilation         |
+| `test`          | Run test suite                 |
+| `test:watch`    | Run tests in watch mode        |
+| `test:coverage` | Generate coverage report       |
+| `lint`          | Lint and fix code              |
+| `format`        | Format code with Prettier      |
+
+### Project Structure
+
+```
+source/                          # TypeScript source code
+├── index.ts                      # Main entry point
+├── runescape/
+│   ├── model/
+│   │   ├── account/             # Player account & skills
+│   │   ├── diaries/             # Achievement diaries
+│   │   ├── quest/               # Quest system
+│   │   │   ├── all/             # Individual quest classes
+│   │   │   └── index.ts         # Quest module export
+│   │   ├── slayer/              # Slayer system
+│   │   ├── Item/                # Item models
+│   │   └── npc/                 # NPC data
+│   ├── tools/                   # Utility tools (ClueScrollHelper, experience calc, etc.)
+│   ├── utils/                   # Helper utilities (cache, validation, etc.)
+│   └── errors.ts                # Custom error types
+└── examples/                    # Usage examples
+
+test/                            # Jest test suite
+└── unit/
+    ├── account/
+    ├── diaries/
+    ├── quest/
+    ├── slayer/
+    ├── model/
+    ├── tools/
+    └── utils/
+
+dist/                            # Compiled output (generated by build)
+```
+
+## Contributing
+
+We welcome contributions! We use [Conventional Commits](https://www.conventionalcommits.org/).
+
+### Getting Started
+
+1. Fork and clone the repository
+2. Create a branch (`feat/amazing-feature`)
+3. Make your changes
+4. Run tests (`npm test && npm run lint`)
+5. Commit with conventional format:
+
+   ```bash
+   feat: add quest requirement validation
+   fix: correct slayer task weights
+   docs: update API documentation
+   ```
+
+6. Push and open a Pull Request
+
+### Guidelines
+
+- Add tests for new features
+- Update documentation for changes
+- Follow existing code style
+- Keep changes focused
+
+## Support
+
+Need help or want to contribute?
+
+- [Report Issues](https://github.com/jamescer/osrs-tools/issues)
+- [Request Features](https://github.com/jamescer/osrs-tools/issues)
+- [Join Discussions](https://github.com/jamescer/osrs-tools/discussions)
+
+## License
+
+[MIT](./LICENSE) © James Cerniglia
+
+## Credits
+
+- **Author**: [James Cerniglia](mailto:jamesmcerniglia@gmail.com)
+- **Contributors**: [View all contributors](https://github.com/jamescer/osrs-tools/graphs/contributors)
+- **Data Source**: [Old School RuneScape Wiki](https://oldschool.runescape.wiki/)

package/dist/examples/ClueScrollExample.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Example usage of ClueScrollHelper
+ * This demonstrates how to use the clue scroll simulation functionality
+ */
+export {};
+//# sourceMappingURL=ClueScrollExample.d.ts.map

package/dist/examples/ClueScrollExample.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClueScrollExample.d.ts","sourceRoot":"","sources":["../../source/examples/ClueScrollExample.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/examples/ClueScrollExample.js

@@ -0,0 +1,30 @@
+/**
+ * Example usage of ClueScrollHelper
+ * This demonstrates how to use the clue scroll simulation functionality
+ */
+import { ClueScrollHelper } from '../runescape/model/clue/ClueScrollHelper';
+// Example 1: Open a single beginner clue casket (returns 1-3 items)
+const beginnerCasket = ClueScrollHelper.openCasket('beginner');
+console.log(`Beginner clue casket with ${beginnerCasket.count} rewards:`, beginnerCasket.items);
+// Example 2: Open an easy clue casket
+const easyCasket = ClueScrollHelper.openCasket('easy');
+console.log(`Easy clue casket with ${easyCasket.count} rewards:`, easyCasket.items);
+// Example 3: Simulate opening 10 caskets (accumulates all items)
+const allRewards = ClueScrollHelper.simulateMultiple('beginner', 10);
+console.log(`10 beginner clue caskets produced ${allRewards.length} total items:`, allRewards);
+// Example 4: Get probability of a specific item
+const flaredTrousersOdds = ClueScrollHelper.getItemProbability('easy', 'Flared trousers');
+console.log(`Probability of Flared trousers per roll: ${flaredTrousersOdds.toFixed(4)} (1/${(1 / flaredTrousersOdds).toFixed(0)})`);
+// Example 5: Get rarity as 1/X
+const rarity = ClueScrollHelper.getItemRarity('easy', 'Willow comp bow');
+console.log(`Willow comp bow rarity: 1/${Math.round(rarity)}`);
+// Example 6: Get all possible rewards for a tier
+const possibleRewards = ClueScrollHelper.getPossibleRewards('easy');
+console.log(`Total possible easy clue rewards: ${possibleRewards.length}`);
+// Example 7: Try all difficulty tiers (shows multi-reward mechanic)
+const tiers = ['beginner', 'easy', 'medium', 'hard', 'elite', 'master'];
+tiers.forEach(tier => {
+    const casket = ClueScrollHelper.openCasket(tier);
+    const itemNames = casket.items.map(item => item.name).join(', ');
+    console.log(`${tier.charAt(0).toUpperCase() + tier.slice(1)} casket (${casket.count} items): ${itemNames}`);
+});

package/dist/examples/ExampleQuest.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ExampleQuest.d.ts.map

package/dist/examples/ExampleQuest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExampleQuest.d.ts","sourceRoot":"","sources":["../../source/examples/ExampleQuest.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OSRS Tools - Main Entry Point
+ * A comprehensive TypeScript library for Old School RuneScape data and utilities
+ *
+ * Core API exports:
+ * - QuestTool: Quest system and utilities
+ * - OsrsAccount: Player account management
+ * - Diaries: Achievement diary system
+ * - ClueScrollHelper: Clue scroll utilities
+ * - Item system and models
+ * - Slayer system and masters
+ *
+ * For individual quests and detailed submodule imports, use subpackage exports:
+ * - import { ... } from 'osrs-tools/quest' - Access all quest classes and utilities
+ * - import { ... } from 'osrs-tools/account' - Account and skill management
+ * - import { ... } from 'osrs-tools/slayer' - Slayer system
+ * - import { ... } from 'osrs-tools/diary' - Achievement diaries
+ * - import { ... } from 'osrs-tools/tools' - Utility tools
+ * - import { ... } from 'osrs-tools/utils' - Helper utilities
+ */
+export * from "./runescape/model/quest/QuestTool";
+export * from "./runescape/model/account/OsrsAccount";
+export * from "./runescape/model/diaries";
+export * from "./runescape/model/clue/ClueScrollHelper";
+export * from "./runescape/model/Item/Item";
+export * from "./runescape/model/Item/models";
+export { SlayerMaster, Task, Assignment, Turael, Spria, Mazchna, Vannaka, Chaeldar, KonarQuoMaten, Nieve, Duradel, Krystilia, SlayerUnlock, SlayerExtend, SlayerBuy, SLAYER_UNLOCKS, SLAYER_EXTENDS, SLAYER_BUYS, SlayerLocation, SlayerBoss, POINTS_TABLE, getMasterByName, getAllMasters, getMastersByMinimumLevel, getMastersByProgression, } from "./runescape/model/slayer";
+export * from "./runescape/model/Requirement";
+export * from "./runescape/errors";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yCAAyC,CAAC;AAGxD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAG9C,OAAO,EACL,YAAY,EACZ,IAAI,EACJ,UAAU,EACV,MAAM,EACN,KAAK,EACL,OAAO,EACP,OAAO,EACP,QAAQ,EACR,aAAa,EACb,KAAK,EACL,OAAO,EACP,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,cAAc,EACd,cAAc,EACd,WAAW,EACX,cAAc,EACd,UAAU,EACV,YAAY,EACZ,eAAe,EACf,aAAa,EACb,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAGlC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oBAAoB,CAAC"}