howlongtobeat-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# howlongtobeat-core
+
+A TypeScript/Deno library to retrieve game completion times from
+[HowLongToBeat.com](https://howlongtobeat.com).
+
+[![JSR](https://jsr.io/badges/howlongtobeat-core)](https://jsr.io/howlongtobeat-core)
+[![npm](https://img.shields.io/npm/v/howlongtobeat-core)](https://www.npmjs.com/package/howlongtobeat-core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🎮 Search games by name or HLTB ID
+- ⏱️ Get completion times (Main Story, Main + Extra, Completionist)
+- 🔍 Dual similarity algorithms (Gestalt & Levenshtein)
+- 🎯 Filter by DLC, mods, or hacks
+- 📦 Works with Deno, Node.js, and browsers
+- 🔒 TypeScript-first with full type definitions
+
+## Installation
+
+### Deno
+
+```typescript
+import { HowLongToBeat } from "jsr:howlongtobeat-core";
+```
+
+### Node.js / npm
+
+```bash
+npm install howlongtobeat-core
+```
+
+```typescript
+import { HowLongToBeat } from "howlongtobeat-core";
+```
+
+## Usage
+
+### Search by Name
+
+```typescript
+import { HowLongToBeat } from "howlongtobeat-core";
+
+const hltb = new HowLongToBeat();
+const results = await hltb.search("Elden Ring");
+
+if (results && results.length > 0) {
+  const game = results[0];
+  console.log(`${game.gameName}`);
+  console.log(`  Main Story: ${game.mainStory} hours`);
+  console.log(`  Main + Extra: ${game.mainExtra} hours`);
+  console.log(`  Completionist: ${game.completionist} hours`);
+}
+```
+
+### Search by ID
+
+```typescript
+const game = await hltb.searchById(68151); // Elden Ring
+console.log(game?.gameName); // "Elden Ring"
+```
+
+### With Options
+
+```typescript
+const hltb = new HowLongToBeat({
+  minimumSimilarity: 0.5, // Filter results below 50% similarity
+  autoFilterTimes: true, // Nullify irrelevant times (e.g., SP times for MP-only games)
+  similarityAlgorithm: "gestalt", // or "levenshtein"
+});
+```
+
+### Filter DLC/Mods
+
+```typescript
+import { HowLongToBeat, SearchModifiers } from "howlongtobeat-core";
+
+const hltb = new HowLongToBeat();
+const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
+```
+
+## API Reference
+
+### `HowLongToBeat`
+
+#### Constructor Options
+
+| Option                | Type                         | Default     | Description                                            |
+| --------------------- | ---------------------------- | ----------- | ------------------------------------------------------ |
+| `minimumSimilarity`   | `number`                     | `0.4`       | Filter results below this similarity threshold (0-1)   |
+| `autoFilterTimes`     | `boolean`                    | `false`     | Auto-nullify irrelevant time fields based on game type |
+| `similarityAlgorithm` | `"gestalt" \| "levenshtein"` | `"gestalt"` | Algorithm for string similarity matching               |
+
+#### Methods
+
+| Method                    | Returns                                 | Description          |
+| ------------------------- | --------------------------------------- | -------------------- |
+| `search(name, modifier?)` | `Promise<HowLongToBeatEntry[] \| null>` | Search games by name |
+| `searchById(id)`          | `Promise<HowLongToBeatEntry \| null>`   | Get game by HLTB ID  |
+
+### `HowLongToBeatEntry`
+
+| Property           | Type               | Description                  |
+| ------------------ | ------------------ | ---------------------------- |
+| `gameId`           | `number`           | HLTB game ID                 |
+| `gameName`         | `string \| null`   | Game title                   |
+| `gameImageUrl`     | `string \| null`   | Cover image URL              |
+| `gameWebLink`      | `string`           | Link to HLTB page            |
+| `mainStory`        | `number \| null`   | Main story time (hours)      |
+| `mainExtra`        | `number \| null`   | Main + extras time (hours)   |
+| `completionist`    | `number \| null`   | 100% completion time (hours) |
+| `allStyles`        | `number \| null`   | Average of all playstyles    |
+| `similarity`       | `number`           | Match similarity (0-1)       |
+| `reviewScore`      | `number \| null`   | User review score            |
+| `profilePlatforms` | `string[] \| null` | Available platforms          |
+| `releaseWorld`     | `number \| null`   | Release year                 |
+
+### `SearchModifiers`
+
+| Value           | Description           |
+| --------------- | --------------------- |
+| `NONE`          | No filter (default)   |
+| `ISOLATE_DLC`   | Only show DLC         |
+| `ISOLATE_MODS`  | Only show mods        |
+| `ISOLATE_HACKS` | Only show hacks       |
+| `HIDE_DLC`      | Hide DLC from results |
+
+## Development
+
+```bash
+# Run tests
+deno task test
+
+# Run unit tests only
+deno task test:unit
+
+# Run integration tests (requires network)
+deno task test:integration
+
+# Type check
+deno task check
+
+# Format code
+deno task fmt
+
+# Lint
+deno task lint
+```
+
+## Credits
+
+This is a TypeScript port of
+[ScrappyCocco/HowLongToBeat-PythonAPI](https://github.com/ScrappyCocco/HowLongToBeat-PythonAPI).
+
+## License
+
+MIT © 2026

package/esm/mod.d.ts

@@ -0,0 +1,30 @@
+/**
+ * HowLongToBeat API for Deno/Node.js
+ *
+ * A TypeScript wrapper for the HowLongToBeat.com website.
+ *
+ * @example
+ * ```typescript
+ * import { HowLongToBeat, SearchModifiers } from "@tapan/howlongtobeat";
+ *
+ * const hltb = new HowLongToBeat({ minimumSimilarity: 0.5 });
+ *
+ * // Search by name
+ * const results = await hltb.search("Elden Ring");
+ * console.log(results?.[0]?.mainStory); // e.g., 50.5 hours
+ *
+ * // Search by ID
+ * const game = await hltb.searchById(10270);
+ * console.log(game?.gameName); // "Elden Ring"
+ *
+ * // Filter DLC
+ * const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
+ * ```
+ *
+ * @module
+ */
+export { HowLongToBeat } from "./src/HowLongToBeat.js";
+export { SearchModifiers } from "./src/types.js";
+export type { HowLongToBeatEntry, HowLongToBeatOptions, SimilarityAlgorithm } from "./src/types.js";
+export { calculateSimilarity, gestaltSimilarity, levenshteinSimilarity } from "./src/utils/similarity.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGpG,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC"}

package/esm/mod.js

@@ -0,0 +1,31 @@
+/**
+ * HowLongToBeat API for Deno/Node.js
+ *
+ * A TypeScript wrapper for the HowLongToBeat.com website.
+ *
+ * @example
+ * ```typescript
+ * import { HowLongToBeat, SearchModifiers } from "@tapan/howlongtobeat";
+ *
+ * const hltb = new HowLongToBeat({ minimumSimilarity: 0.5 });
+ *
+ * // Search by name
+ * const results = await hltb.search("Elden Ring");
+ * console.log(results?.[0]?.mainStory); // e.g., 50.5 hours
+ *
+ * // Search by ID
+ * const game = await hltb.searchById(10270);
+ * console.log(game?.gameName); // "Elden Ring"
+ *
+ * // Filter DLC
+ * const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
+ * ```
+ *
+ * @module
+ */
+// Main class
+export { HowLongToBeat } from "./src/HowLongToBeat.js";
+// Types and enums
+export { SearchModifiers } from "./src/types.js";
+// Utility exports for advanced usage
+export { calculateSimilarity, gestaltSimilarity, levenshteinSimilarity } from "./src/utils/similarity.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/src/HowLongToBeat.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Main HowLongToBeat class
+ *
+ * Provides methods to search for games on HowLongToBeat.com
+ */
+import type { HowLongToBeatEntry, HowLongToBeatOptions } from "./types.js";
+import { SearchModifiers } from "./types.js";
+/**
+ * HowLongToBeat API wrapper
+ *
+ * @example
+ * ```typescript
+ * const hltb = new HowLongToBeat();
+ * const results = await hltb.search("The Witcher 3");
+ * console.log(results);
+ * ```
+ */
+export declare class HowLongToBeat {
+    private readonly minimumSimilarity;
+    private readonly autoFilterTimes;
+    private readonly similarityAlgorithm;
+    private readonly similarityCalculator;
+    /**
+     * Create a new HowLongToBeat instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: HowLongToBeatOptions);
+    /**
+     * Search for games by name
+     *
+     * @param gameName - The name of the game to search for
+     * @param modifier - Optional search modifier to filter results
+     * @returns Array of matching games sorted by similarity, or null on error
+     *
+     * @example
+     * ```typescript
+     * const hltb = new HowLongToBeat();
+     * const results = await hltb.search("Elden Ring");
+     * if (results && results.length > 0) {
+     *   console.log(`Main story: ${results[0].mainStory} hours`);
+     * }
+     * ```
+     */
+    search(gameName: string, modifier?: SearchModifiers): Promise<HowLongToBeatEntry[] | null>;
+    /**
+     * Search for a game by its HLTB ID
+     *
+     * @param gameId - The unique game ID on HowLongToBeat
+     * @returns The matching game entry, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const hltb = new HowLongToBeat();
+     * const game = await hltb.searchById(10270); // Elden Ring
+     * if (game) {
+     *   console.log(`${game.gameName}: ${game.mainStory} hours`);
+     * }
+     * ```
+     */
+    searchById(gameId: number): Promise<HowLongToBeatEntry | null>;
+}
+//# sourceMappingURL=HowLongToBeat.d.ts.map

package/esm/src/HowLongToBeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HowLongToBeat.d.ts","sourceRoot":"","sources":["../../src/src/HowLongToBeat.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAkB7C;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAmC;IAExE;;;;OAIG;gBACS,OAAO,GAAE,oBAAyB;IAY9C;;;;;;;;;;;;;;;OAeG;IACG,MAAM,CACV,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,eAAsC,GAC/C,OAAO,CAAC,kBAAkB,EAAE,GAAG,IAAI,CAAC;IAuBvC;;;;;;;;;;;;;;OAcG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;CA8CrE"}

package/esm/src/HowLongToBeat.js

@@ -0,0 +1,142 @@
+/**
+ * Main HowLongToBeat class
+ *
+ * Provides methods to search for games on HowLongToBeat.com
+ */
+import { SearchModifiers } from "./types.js";
+import { executeSearch, extractGameTitle, fetchGamePage, } from "./http/client.js";
+import { filterBySimilarity, parseGameEntries } from "./parser/json.js";
+import { createSimilarityCalculator } from "./utils/similarity.js";
+/**
+ * Default options for HowLongToBeat
+ */
+const DEFAULT_OPTIONS = {
+    minimumSimilarity: 0.4,
+    autoFilterTimes: false,
+    similarityAlgorithm: "gestalt",
+};
+/**
+ * HowLongToBeat API wrapper
+ *
+ * @example
+ * ```typescript
+ * const hltb = new HowLongToBeat();
+ * const results = await hltb.search("The Witcher 3");
+ * console.log(results);
+ * ```
+ */
+export class HowLongToBeat {
+    /**
+     * Create a new HowLongToBeat instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options = {}) {
+        Object.defineProperty(this, "minimumSimilarity", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "autoFilterTimes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "similarityAlgorithm", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "similarityCalculator", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.minimumSimilarity = options.minimumSimilarity ??
+            DEFAULT_OPTIONS.minimumSimilarity;
+        this.autoFilterTimes = options.autoFilterTimes ??
+            DEFAULT_OPTIONS.autoFilterTimes;
+        this.similarityAlgorithm = options.similarityAlgorithm ??
+            DEFAULT_OPTIONS.similarityAlgorithm;
+        this.similarityCalculator = createSimilarityCalculator(this.similarityAlgorithm);
+    }
+    /**
+     * Search for games by name
+     *
+     * @param gameName - The name of the game to search for
+     * @param modifier - Optional search modifier to filter results
+     * @returns Array of matching games sorted by similarity, or null on error
+     *
+     * @example
+     * ```typescript
+     * const hltb = new HowLongToBeat();
+     * const results = await hltb.search("Elden Ring");
+     * if (results && results.length > 0) {
+     *   console.log(`Main story: ${results[0].mainStory} hours`);
+     * }
+     * ```
+     */
+    async search(gameName, modifier = SearchModifiers.NONE) {
+        if (!gameName || gameName.trim().length === 0) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        const response = await executeSearch(gameName.trim(), modifier);
+        if (!response || !response.data) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        const entries = parseGameEntries(response.data, gameName, this.autoFilterTimes, this.similarityCalculator);
+        return filterBySimilarity(entries, this.minimumSimilarity);
+    }
+    /**
+     * Search for a game by its HLTB ID
+     *
+     * @param gameId - The unique game ID on HowLongToBeat
+     * @returns The matching game entry, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const hltb = new HowLongToBeat();
+     * const game = await hltb.searchById(10270); // Elden Ring
+     * if (game) {
+     *   console.log(`${game.gameName}: ${game.mainStory} hours`);
+     * }
+     * ```
+     */
+    async searchById(gameId) {
+        if (!gameId || gameId <= 0) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        // First, fetch the game page to get the title
+        const html = await fetchGamePage(gameId);
+        if (!html) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        const gameTitle = extractGameTitle(html);
+        if (!gameTitle) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        // Search using the extracted title
+        const response = await executeSearch(gameTitle);
+        if (!response || !response.data) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        // Find the exact game by ID
+        const matchingGame = response.data.find((game) => game.game_id === gameId);
+        if (!matchingGame) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        const entries = parseGameEntries([matchingGame], gameTitle, this.autoFilterTimes, this.similarityCalculator);
+        return entries.length > 0 ? entries[0] : null;
+    }
+}

package/esm/src/http/client.d.ts

@@ -0,0 +1,29 @@
+/**
+ * HTTP client for HowLongToBeat API
+ */
+import type { HLTBSearchRequest, HLTBSearchResponse } from "../types.js";
+/**
+ * Build search request body
+ */
+export declare function buildSearchRequest(searchTerms: string[], modifier?: string, page?: number, size?: number): HLTBSearchRequest;
+/**
+ * Execute a search request to HLTB API
+ */
+export declare function executeSearch(gameName: string, modifier?: string): Promise<HLTBSearchResponse | null>;
+/**
+ * Fetch game page HTML to extract game title
+ */
+export declare function fetchGamePage(gameId: number): Promise<string | null>;
+/**
+ * Extract game title from HLTB game page HTML
+ */
+export declare function extractGameTitle(html: string): string | null;
+/**
+ * Get base URL for constructing image and web links
+ */
+export declare function getBaseUrl(): string;
+/**
+ * Clear cached token and search URL (useful for testing)
+ */
+export declare function clearCache(): void;
+//# sourceMappingURL=client.d.ts.map

package/esm/src/http/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/src/http/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAqJzE;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EAAE,EACrB,QAAQ,GAAE,MAAW,EACrB,IAAI,GAAE,MAAU,EAChB,IAAI,GAAE,MAAW,GAChB,iBAAiB,CA8BnB;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAW,GACpB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAmCpC;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoB1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY5D;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAIjC"}