howlongtobeat-core 0.1.0

package/esm/src/utils/similarity.js

@@ -0,0 +1,127 @@
+/**
+ * String similarity algorithms for HowLongToBeat
+ *
+ * Provides both Gestalt pattern matching (like Python's difflib.SequenceMatcher)
+ * and Levenshtein distance-based similarity.
+ */
+/**
+ * Calculate similarity using the specified algorithm
+ */
+export function calculateSimilarity(a, b, algorithm = "gestalt") {
+    if (algorithm === "levenshtein") {
+        return levenshteinSimilarity(a, b);
+    }
+    return gestaltSimilarity(a, b);
+}
+/**
+ * Gestalt Pattern Matching similarity (like Python's difflib.SequenceMatcher)
+ *
+ * This implements the Ratcliff/Obershelp algorithm which finds the longest
+ * common substring and recursively processes the remaining parts.
+ */
+export function gestaltSimilarity(a, b) {
+    if (a === b)
+        return 1.0;
+    if (a.length === 0 || b.length === 0)
+        return 0.0;
+    const matches = countMatchingCharacters(a, b);
+    return (2.0 * matches) / (a.length + b.length);
+}
+/**
+ * Count matching characters using Ratcliff/Obershelp algorithm
+ */
+function countMatchingCharacters(a, b) {
+    const [lcs, aStart, aEnd, bStart, bEnd] = findLongestCommonSubstring(a, b);
+    if (lcs === 0) {
+        return 0;
+    }
+    let count = lcs;
+    // Recursively process left parts
+    if (aStart > 0 && bStart > 0) {
+        count += countMatchingCharacters(a.substring(0, aStart), b.substring(0, bStart));
+    }
+    // Recursively process right parts
+    if (aEnd < a.length && bEnd < b.length) {
+        count += countMatchingCharacters(a.substring(aEnd), b.substring(bEnd));
+    }
+    return count;
+}
+/**
+ * Find the longest common substring between two strings
+ * Returns [length, aStart, aEnd, bStart, bEnd]
+ */
+function findLongestCommonSubstring(a, b) {
+    let longestLength = 0;
+    let aStart = 0;
+    let bStart = 0;
+    // Build a table of matching positions
+    const table = Array(a.length + 1)
+        .fill(null)
+        .map(() => Array(b.length + 1).fill(0));
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            if (a[i - 1] === b[j - 1]) {
+                table[i][j] = table[i - 1][j - 1] + 1;
+                if (table[i][j] > longestLength) {
+                    longestLength = table[i][j];
+                    aStart = i - longestLength;
+                    bStart = j - longestLength;
+                }
+            }
+        }
+    }
+    return [
+        longestLength,
+        aStart,
+        aStart + longestLength,
+        bStart,
+        bStart + longestLength,
+    ];
+}
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+function levenshteinDistance(a, b) {
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const matrix = [];
+    // Initialize first column
+    for (let i = 0; i <= a.length; i++) {
+        matrix[i] = [i];
+    }
+    // Initialize first row
+    for (let j = 0; j <= b.length; j++) {
+        matrix[0][j] = j;
+    }
+    // Fill in the rest of the matrix
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, // deletion
+            matrix[i][j - 1] + 1, // insertion
+            matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[a.length][b.length];
+}
+/**
+ * Calculate similarity based on Levenshtein distance
+ * Returns a value between 0 and 1, where 1 means identical strings
+ */
+export function levenshteinSimilarity(a, b) {
+    if (a === b)
+        return 1.0;
+    if (a.length === 0 || b.length === 0)
+        return 0.0;
+    const distance = levenshteinDistance(a, b);
+    const maxLength = Math.max(a.length, b.length);
+    return 1 - distance / maxLength;
+}
+/**
+ * Create a similarity calculator function with a specific algorithm
+ */
+export function createSimilarityCalculator(algorithm = "gestalt") {
+    return (a, b) => calculateSimilarity(a, b, algorithm);
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "howlongtobeat-core",
+  "version": "0.1.0",
+  "description": "TypeScript library to retrieve game completion times from HowLongToBeat.com",
+  "keywords": [
+    "howlongtobeat",
+    "hltb",
+    "games",
+    "gaming",
+    "playtime",
+    "game-time",
+    "completion-time",
+    "api"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tapanmeena/howlongtobeat-core.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/tapanmeena/howlongtobeat-core/issues"
+  },
+  "main": "./script/mod.js",
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "import": "./esm/mod.js",
+      "require": "./script/mod.js"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.0"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/script/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/script/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/script/mod.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshteinSimilarity = exports.gestaltSimilarity = exports.calculateSimilarity = exports.SearchModifiers = exports.HowLongToBeat = void 0;
+// Main class
+var HowLongToBeat_js_1 = require("./src/HowLongToBeat.js");
+Object.defineProperty(exports, "HowLongToBeat", { enumerable: true, get: function () { return HowLongToBeat_js_1.HowLongToBeat; } });
+// Types and enums
+var types_js_1 = require("./src/types.js");
+Object.defineProperty(exports, "SearchModifiers", { enumerable: true, get: function () { return types_js_1.SearchModifiers; } });
+// Utility exports for advanced usage
+var similarity_js_1 = require("./src/utils/similarity.js");
+Object.defineProperty(exports, "calculateSimilarity", { enumerable: true, get: function () { return similarity_js_1.calculateSimilarity; } });
+Object.defineProperty(exports, "gestaltSimilarity", { enumerable: true, get: function () { return similarity_js_1.gestaltSimilarity; } });
+Object.defineProperty(exports, "levenshteinSimilarity", { enumerable: true, get: function () { return similarity_js_1.levenshteinSimilarity; } });

package/script/package.json

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

package/script/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/script/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/script/src/HowLongToBeat.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Main HowLongToBeat class
+ *
+ * Provides methods to search for games on HowLongToBeat.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HowLongToBeat = void 0;
+const types_js_1 = require("./types.js");
+const client_js_1 = require("./http/client.js");
+const json_js_1 = require("./parser/json.js");
+const similarity_js_1 = require("./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);
+ * ```
+ */
+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 = (0, similarity_js_1.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 = types_js_1.SearchModifiers.NONE) {
+        if (!gameName || gameName.trim().length === 0) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        const response = await (0, client_js_1.executeSearch)(gameName.trim(), modifier);
+        if (!response || !response.data) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        const entries = (0, json_js_1.parseGameEntries)(response.data, gameName, this.autoFilterTimes, this.similarityCalculator);
+        return (0, json_js_1.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 (0, client_js_1.fetchGamePage)(gameId);
+        if (!html) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        const gameTitle = (0, client_js_1.extractGameTitle)(html);
+        if (!gameTitle) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        // Search using the extracted title
+        const response = await (0, client_js_1.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 = (0, json_js_1.parseGameEntries)([matchingGame], gameTitle, this.autoFilterTimes, this.similarityCalculator);
+        return entries.length > 0 ? entries[0] : null;
+    }
+}
+exports.HowLongToBeat = HowLongToBeat;

package/script/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/script/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"}