howlongtobeat-core 0.1.0 → 1.1.0

package/README.md

@@ -3,18 +3,19 @@
 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)
+[![JSR](https://jsr.io/badges/@tapan/howlongtobeat)](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
+- Search games by name or HLTB ID
+- Get completion times (Main Story, Main + Extra, Completionist)
+- Get game statistics (releases, ratings, popular games by year/platform)
+- 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
 
@@ -60,6 +61,30 @@ const game = await hltb.searchById(68151); // Elden Ring
 console.log(game?.gameName); // "Elden Ring"
 ```
 
+### Get Game Statistics
+
+```typescript
+// Get stats for a specific year (returns monthly breakdown)
+const stats2026 = await hltb.getGameStats({ year: "2026" });
+if (stats2026) {
+  console.log(`Total releases: ${stats2026.breakdown.totalReleases}`);
+  console.log(`Average time: ${stats2026.breakdown.avgTime}`);
+  console.log(`Average rating: ${stats2026.breakdown.avgRating}`);
+  console.log(`Monthly breakdown:`, stats2026.months);
+}
+
+// Get all-time stats (returns yearly breakdown)
+const allTimeStats = await hltb.getGameStats();
+console.log(`Yearly breakdown:`, allTimeStats?.years);
+
+// Filter by platform, genre, perspective, etc.
+const pcStats = await hltb.getGameStats({
+  platform: "PC",
+  year: "2026",
+  genre: "RPG",
+});
+```
+
 ### With Options
 
 ```typescript
@@ -97,6 +122,7 @@ const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
 | ------------------------- | --------------------------------------- | -------------------- |
 | `search(name, modifier?)` | `Promise<HowLongToBeatEntry[] \| null>` | Search games by name |
 | `searchById(id)`          | `Promise<HowLongToBeatEntry \| null>`   | Get game by HLTB ID  |
+| `getGameStats(options?)`  | `Promise<GameStatsResponse \| null>`    | Get game statistics  |
 
 ### `HowLongToBeatEntry`
 
@@ -125,6 +151,31 @@ const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
 | `ISOLATE_HACKS` | Only show hacks       |
 | `HIDE_DLC`      | Hide DLC from results |
 
+### `GameStatsOptions`
+
+| Option        | Type     | Description                                      |
+| ------------- | -------- | ------------------------------------------------ |
+| `platform`    | `string` | Filter by platform (e.g., "PC", "PlayStation 5") |
+| `year`        | `string` | Filter by year (e.g., "2026")                    |
+| `perspective` | `string` | Filter by perspective (e.g., "First-Person")     |
+| `flow`        | `string` | Filter by pacing/flow                            |
+| `genre`       | `string` | Filter by genre (e.g., "RPG", "Action")          |
+
+### `GameStatsResponse`
+
+| Property                 | Type                     | Description                             |
+| ------------------------ | ------------------------ | --------------------------------------- |
+| `tags`                   | `StatsTags`              | Applied filter tags                     |
+| `breakdown`              | `StatsBreakdown`         | Summary stats (releases, avgTime, etc.) |
+| `months`                 | `Record<string, number>` | Monthly distribution (when year set)    |
+| `years`                  | `Record<string, number>` | Yearly distribution (when year not set) |
+| `platformList`           | `PlatformCount[]`        | Games per platform                      |
+| `categoryMostBacklogged` | `CategoryEntry[]`        | Most backlogged games                   |
+| `categoryMostCompleted`  | `CategoryEntry[]`        | Most completed games                    |
+| `categoryBestRated`      | `CategoryEntry[]`        | Highest rated games                     |
+| `categoryTopPlaying`     | `CategoryEntry[]`        | Currently most played games             |
+| `popularGames`           | `PopularGameEntry[]`     | Popular games list                      |
+
 ## Development
 
 ```bash

package/esm/mod.d.ts

@@ -19,12 +19,21 @@
  *
  * // Filter DLC
  * const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
+ *
+ * // Get game statistics for a year
+ * const stats = await hltb.getGameStats({ year: "2026" });
+ * console.log(stats?.breakdown.totalReleases); // e.g., 771
+ * console.log(stats?.popularGames[0]?.title); // Most popular game
+ *
+ * // Get all-time stats (yearly breakdown)
+ * const allTime = await hltb.getGameStats();
+ * console.log(allTime?.years); // { "2020": 1000, "2021": 1200, ... }
  * ```
  *
  * @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";
+export type { CategoryEntry, GameStatsOptions, GameStatsResponse, HowLongToBeatEntry, HowLongToBeatOptions, PlatformCount, PopularGameEntry, SimilarityAlgorithm, StatsBreakdown, StatsTags, } from "./src/types.js";
+export { calculateSimilarity, gestaltSimilarity, levenshteinSimilarity, } from "./src/utils/similarity.js";
 //# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,SAAS,GACV,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC"}

package/esm/mod.js

@@ -19,6 +19,15 @@
  *
  * // Filter DLC
  * const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
+ *
+ * // Get game statistics for a year
+ * const stats = await hltb.getGameStats({ year: "2026" });
+ * console.log(stats?.breakdown.totalReleases); // e.g., 771
+ * console.log(stats?.popularGames[0]?.title); // Most popular game
+ *
+ * // Get all-time stats (yearly breakdown)
+ * const allTime = await hltb.getGameStats();
+ * console.log(allTime?.years); // { "2020": 1000, "2021": 1200, ... }
  * ```
  *
  * @module
@@ -28,4 +37,4 @@ 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";
+export { calculateSimilarity, gestaltSimilarity, levenshteinSimilarity, } from "./src/utils/similarity.js";

package/esm/src/HowLongToBeat.d.ts

@@ -3,7 +3,7 @@
  *
  * Provides methods to search for games on HowLongToBeat.com
  */
-import type { HowLongToBeatEntry, HowLongToBeatOptions } from "./types.js";
+import type { GameStatsOptions, GameStatsResponse, HowLongToBeatEntry, HowLongToBeatOptions } from "./types.js";
 import { SearchModifiers } from "./types.js";
 /**
  * HowLongToBeat API wrapper
@@ -59,5 +59,29 @@ export declare class HowLongToBeat {
      * ```
      */
     searchById(gameId: number): Promise<HowLongToBeatEntry | null>;
+    /**
+     * Get game statistics from HowLongToBeat
+     *
+     * @param options - Optional filters for platform, year, perspective, flow, genre
+     * @returns Game statistics including breakdowns, platform counts, and category rankings
+     *
+     * @example
+     * ```typescript
+     * const hltb = new HowLongToBeat();
+     *
+     * // Get stats for 2026
+     * const stats = await hltb.getGameStats({ year: "2026" });
+     * console.log(stats?.breakdown.totalReleases); // e.g., 771
+     * console.log(stats?.months); // Monthly distribution
+     *
+     * // Get all-time stats (yearly distribution)
+     * const allTime = await hltb.getGameStats();
+     * console.log(allTime?.years); // Yearly distribution
+     *
+     * // Filter by platform
+     * const pcStats = await hltb.getGameStats({ platform: "PC", year: "2026" });
+     * ```
+     */
+    getGameStats(options?: GameStatsOptions): Promise<GameStatsResponse | null>;
 }
 //# sourceMappingURL=HowLongToBeat.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"HowLongToBeat.d.ts","sourceRoot":"","sources":["../../src/src/HowLongToBeat.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAuB7C;;;;;;;;;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;IA+CpE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,YAAY,CAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CAUrC"}

package/esm/src/HowLongToBeat.js

@@ -4,8 +4,8 @@
  * 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 { executeSearch, extractGameTitle, fetchGamePage, fetchGameStats, } from "./http/client.js";
+import { filterBySimilarity, parseGameEntries, parseGameStats, } from "./parser/json.js";
 import { createSimilarityCalculator } from "./utils/similarity.js";
 /**
  * Default options for HowLongToBeat
@@ -139,4 +139,35 @@ export class HowLongToBeat {
         const entries = parseGameEntries([matchingGame], gameTitle, this.autoFilterTimes, this.similarityCalculator);
         return entries.length > 0 ? entries[0] : null;
     }
+    /**
+     * Get game statistics from HowLongToBeat
+     *
+     * @param options - Optional filters for platform, year, perspective, flow, genre
+     * @returns Game statistics including breakdowns, platform counts, and category rankings
+     *
+     * @example
+     * ```typescript
+     * const hltb = new HowLongToBeat();
+     *
+     * // Get stats for 2026
+     * const stats = await hltb.getGameStats({ year: "2026" });
+     * console.log(stats?.breakdown.totalReleases); // e.g., 771
+     * console.log(stats?.months); // Monthly distribution
+     *
+     * // Get all-time stats (yearly distribution)
+     * const allTime = await hltb.getGameStats();
+     * console.log(allTime?.years); // Yearly distribution
+     *
+     * // Filter by platform
+     * const pcStats = await hltb.getGameStats({ platform: "PC", year: "2026" });
+     * ```
+     */
+    async getGameStats(options = {}) {
+        const response = await fetchGameStats(options);
+        if (!response) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        return parseGameStats(response);
+    }
 }

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

@@ -1,7 +1,7 @@
 /**
  * HTTP client for HowLongToBeat API
  */
-import type { HLTBSearchRequest, HLTBSearchResponse } from "../types.js";
+import type { GameStatsOptions, GameStatsResponse, HLTBSearchRequest, HLTBSearchResponse } from "../types.js";
 /**
  * Build search request body
  */
@@ -22,6 +22,13 @@ export declare function extractGameTitle(html: string): string | null;
  * Get base URL for constructing image and web links
  */
 export declare function getBaseUrl(): string;
+/**
+ * Fetch game statistics from HLTB API
+ *
+ * @param options - Optional filters for the stats query
+ * @returns Game statistics response, or null on error
+ */
+export declare function fetchGameStats(options?: GameStatsOptions): Promise<GameStatsResponse | null>;
 /**
  * Clear cached token and search URL (useful for testing)
  */

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

@@ -1 +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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/src/http/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAsJrB;;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;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAgCnC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAIjC"}

package/esm/src/http/client.js

@@ -2,6 +2,7 @@
  * HTTP client for HowLongToBeat API
  */
 const HLTB_BASE_URL = "https://howlongtobeat.com";
+const HLTB_STATS_URL = `${HLTB_BASE_URL}/api/stats/games`;
 const HLTB_SEARCH_URL = `${HLTB_BASE_URL}/api/search`;
 const HLTB_GAME_URL = `${HLTB_BASE_URL}/game`;
 /**
@@ -240,6 +241,42 @@ export function extractGameTitle(html) {
 export function getBaseUrl() {
     return HLTB_BASE_URL;
 }
+/**
+ * Fetch game statistics from HLTB API
+ *
+ * @param options - Optional filters for the stats query
+ * @returns Game statistics response, or null on error
+ */
+export async function fetchGameStats(options = {}) {
+    // TODO: Add filter validation for platform, year, perspective, flow, genre
+    const params = new URLSearchParams({
+        platform: options.platform ?? "",
+        year: options.year ?? "",
+        perspective: options.perspective ?? "",
+        flow: options.flow ?? "",
+        genre: options.genre ?? "",
+    });
+    try {
+        const response = await fetch(`${HLTB_STATS_URL}?${params.toString()}`, {
+            method: "GET",
+            headers: {
+                "User-Agent": getRandomUserAgent(),
+                "Referer": HLTB_BASE_URL,
+            },
+        });
+        if (!response.ok) {
+            // TODO: implement proper error handling
+            console.error(`Stats request failed: ${response.status}`);
+            return null;
+        }
+        return await response.json();
+    }
+    catch (error) {
+        // TODO: implement proper error handling
+        console.error("Error fetching game stats:", error);
+        return null;
+    }
+}
 /**
  * Clear cached token and search URL (useful for testing)
  */

package/esm/src/parser/json.d.ts

@@ -14,4 +14,15 @@ export declare function parseGameEntries(rawGames: HLTBRawGame[], searchQuery: s
  * Filter entries by minimum similarity threshold
  */
 export declare function filterBySimilarity(entries: HowLongToBeatEntry[], minimumSimilarity: number): HowLongToBeatEntry[];
+import type { GameStatsResponse } from "../types.js";
+/**
+ * Parse game stats response from HLTB API
+ *
+ * Currently passes through the response as-is since the API response
+ * structure matches our type definition.
+ *
+ * @param raw - Raw API response
+ * @returns Parsed game stats response
+ */
+export declare function parseGameStats(raw: GameStatsResponse): GameStatsResponse;
 //# sourceMappingURL=json.d.ts.map

package/esm/src/parser/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/src/parser/json.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA2BnE;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,WAAW,EAChB,UAAU,GAAE,MAAU,EACtB,eAAe,GAAE,OAAe,GAC/B,kBAAkB,CAyEpB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,OAAO,EACxB,mBAAmB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,GACpD,kBAAkB,EAAE,CAgBtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAAE,EAC7B,iBAAiB,EAAE,MAAM,GACxB,kBAAkB,EAAE,CAItB"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/src/parser/json.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA2BnE;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,WAAW,EAChB,UAAU,GAAE,MAAU,EACtB,eAAe,GAAE,OAAe,GAC/B,kBAAkB,CAyEpB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,OAAO,EACxB,mBAAmB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,GACpD,kBAAkB,EAAE,CAgBtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAAE,EAC7B,iBAAiB,EAAE,MAAM,GACxB,kBAAkB,EAAE,CAItB;AAED,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,iBAAiB,GACrB,iBAAiB,CAKnB"}

package/esm/src/parser/json.js

@@ -111,3 +111,18 @@ export function filterBySimilarity(entries, minimumSimilarity) {
         .filter((entry) => entry.similarity >= minimumSimilarity)
         .sort((a, b) => b.similarity - a.similarity);
 }
+/**
+ * Parse game stats response from HLTB API
+ *
+ * Currently passes through the response as-is since the API response
+ * structure matches our type definition.
+ *
+ * @param raw - Raw API response
+ * @returns Parsed game stats response
+ */
+export function parseGameStats(raw) {
+    // The API response structure matches our type definition,
+    // so we pass it through. This function exists for consistency
+    // with other parsers and future transformation needs.
+    return raw;
+}

package/esm/src/types.d.ts

@@ -176,4 +176,104 @@ export interface HLTBSearchRequest {
     };
     useCache: boolean;
 }
+/**
+ * Options for filtering game statistics
+ */
+export interface GameStatsOptions {
+    /** Filter by platform (e.g., "PC", "PlayStation 5") */
+    platform?: string;
+    /** Filter by year (e.g., "2026"). If omitted, returns yearly aggregates instead of monthly */
+    year?: string;
+    /** Filter by perspective (e.g., "First-Person", "Third-Person") */
+    perspective?: string;
+    /** Filter by flow/pacing */
+    flow?: string;
+    /** Filter by genre */
+    genre?: string;
+}
+/**
+ * Tags/filters applied to the stats query
+ */
+export interface StatsTags {
+    genres: string;
+    platform: string;
+    year: string;
+}
+/**
+ * Breakdown statistics for the filtered games
+ */
+export interface StatsBreakdown {
+    /** Total number of game releases */
+    totalReleases: number;
+    /** Average completion time (formatted string like "14h 8m") */
+    avgTime: string;
+    /** Average review rating (0-100) */
+    avgRating: number;
+    /** Number of playthroughs */
+    playthroughs: string;
+}
+/**
+ * Platform count entry
+ */
+export interface PlatformCount {
+    platform: string;
+    count_total: number;
+}
+/**
+ * Category entry for various rankings (most backlogged, completed, etc.)
+ */
+export interface CategoryEntry {
+    game_id: number;
+    game_name: string;
+    stat: number;
+}
+/**
+ * Popular game entry with additional metadata
+ */
+export interface PopularGameEntry {
+    id: number;
+    title: string;
+    platform: string;
+    class: string;
+    /** Release date in "YYYY-MM-DD" format */
+    stats: string;
+    popular: number;
+}
+/**
+ * Game statistics response from HLTB API
+ */
+export interface GameStatsResponse {
+    /** Applied filter tags */
+    tags: StatsTags;
+    /** Summary breakdown statistics */
+    breakdown: StatsBreakdown;
+    /** Monthly distribution (keys "00"-"12", present when year is specified) */
+    months?: Record<string, number>;
+    /** Yearly distribution (present when year is not specified) */
+    years?: Record<string, number>;
+    /** Games per platform */
+    platformList: PlatformCount[];
+    /** Games with most backlog entries */
+    categoryMostBacklogged: CategoryEntry[];
+    /** Games with most speedruns */
+    categoryMostSpeedruns: CategoryEntry[];
+    /** Games with most completions */
+    categoryMostCompleted: CategoryEntry[];
+    /** Games with most retired/dropped entries */
+    categoryMostRetired: CategoryEntry[];
+    /** Highest rated games */
+    categoryBestRated: CategoryEntry[];
+    /** Lowest rated games */
+    categoryWorstRated: CategoryEntry[];
+    /** Games currently being played the most */
+    categoryTopPlaying: CategoryEntry[];
+    /** Most reviewed games */
+    categoryMostReviews: CategoryEntry[];
+    /** Longest games by completion time */
+    categoryLongestGames: CategoryEntry[];
+    /** Shortest games by completion time */
+    categoryShortestGames: CategoryEntry[];
+    /** Currently popular games */
+    popularGames: PopularGameEntry[];
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,oBAAY,eAAe;IACzB,wCAAwC;IACxC,IAAI,KAAK;IACT,4BAA4B;IAC5B,WAAW,aAAa;IACxB,qBAAqB;IACrB,YAAY,cAAc;IAC1B,sBAAsB;IACtB,aAAa,eAAe;IAC5B,4BAA4B;IAC5B,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,aAAa,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sDAAsD;IACtD,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;CAC3C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oCAAoC;IACpC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IAGpB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qBAAqB;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,0BAA0B;IAC1B,gBAAgB,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC,mBAAmB;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAG5B,iCAAiC;IACjC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8BAA8B;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gCAAgC;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,uBAAuB;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAGtB,iCAAiC;IACjC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,+BAA+B;IAC/B,eAAe,EAAE,OAAO,CAAC;IACzB,wBAAwB;IACxB,eAAe,EAAE,OAAO,CAAC;IACzB,8BAA8B;IAC9B,eAAe,EAAE,OAAO,CAAC;IAGzB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IAEnB,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,WAAW,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE;QACb,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,YAAY,EAAE,MAAM,CAAC;YACrB,aAAa,EAAE,MAAM,CAAC;YACtB,SAAS,EAAE;gBAAE,GAAG,EAAE,MAAM,CAAC;gBAAC,GAAG,EAAE,MAAM,CAAA;aAAE,CAAC;YACxC,QAAQ,EAAE;gBACR,WAAW,EAAE,MAAM,CAAC;gBACpB,IAAI,EAAE,MAAM,CAAC;gBACb,KAAK,EAAE,MAAM,CAAC;gBACd,UAAU,EAAE,MAAM,CAAC;aACpB,CAAC;YACF,SAAS,EAAE;gBAAE,GAAG,EAAE,MAAM,CAAC;gBAAC,GAAG,EAAE,MAAM,CAAA;aAAE,CAAC;YACxC,QAAQ,EAAE,MAAM,CAAC;SAClB,CAAC;QACF,KAAK,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,CAAC;QAChC,KAAK,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,CAAC;QAChC,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0BAA0B;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,mCAAmC;IACnC,SAAS,EAAE,cAAc,CAAC;IAC1B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yBAAyB;IACzB,YAAY,EAAE,aAAa,EAAE,CAAC;IAC9B,sCAAsC;IACtC,sBAAsB,EAAE,aAAa,EAAE,CAAC;IACxC,gCAAgC;IAChC,qBAAqB,EAAE,aAAa,EAAE,CAAC;IACvC,kCAAkC;IAClC,qBAAqB,EAAE,aAAa,EAAE,CAAC;IACvC,8CAA8C;IAC9C,mBAAmB,EAAE,aAAa,EAAE,CAAC;IACrC,0BAA0B;IAC1B,iBAAiB,EAAE,aAAa,EAAE,CAAC;IACnC,yBAAyB;IACzB,kBAAkB,EAAE,aAAa,EAAE,CAAC;IACpC,4CAA4C;IAC5C,kBAAkB,EAAE,aAAa,EAAE,CAAC;IACpC,0BAA0B;IAC1B,mBAAmB,EAAE,aAAa,EAAE,CAAC;IACrC,uCAAuC;IACvC,oBAAoB,EAAE,aAAa,EAAE,CAAC;IACtC,wCAAwC;IACxC,qBAAqB,EAAE,aAAa,EAAE,CAAC;IACvC,8BAA8B;IAC9B,YAAY,EAAE,gBAAgB,EAAE,CAAC;CAClC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howlongtobeat-core",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "TypeScript library to retrieve game completion times from HowLongToBeat.com",
   "keywords": [
     "howlongtobeat",

package/script/mod.d.ts

@@ -19,12 +19,21 @@
  *
  * // Filter DLC
  * const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
+ *
+ * // Get game statistics for a year
+ * const stats = await hltb.getGameStats({ year: "2026" });
+ * console.log(stats?.breakdown.totalReleases); // e.g., 771
+ * console.log(stats?.popularGames[0]?.title); // Most popular game
+ *
+ * // Get all-time stats (yearly breakdown)
+ * const allTime = await hltb.getGameStats();
+ * console.log(allTime?.years); // { "2020": 1000, "2021": 1200, ... }
  * ```
  *
  * @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";
+export type { CategoryEntry, GameStatsOptions, GameStatsResponse, HowLongToBeatEntry, HowLongToBeatOptions, PlatformCount, PopularGameEntry, SimilarityAlgorithm, StatsBreakdown, StatsTags, } from "./src/types.js";
+export { calculateSimilarity, gestaltSimilarity, levenshteinSimilarity, } from "./src/utils/similarity.js";
 //# sourceMappingURL=mod.d.ts.map

package/script/mod.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,SAAS,GACV,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC"}

package/script/mod.js

@@ -20,6 +20,15 @@
  *
  * // Filter DLC
  * const dlcOnly = await hltb.search("Dark Souls", SearchModifiers.ISOLATE_DLC);
+ *
+ * // Get game statistics for a year
+ * const stats = await hltb.getGameStats({ year: "2026" });
+ * console.log(stats?.breakdown.totalReleases); // e.g., 771
+ * console.log(stats?.popularGames[0]?.title); // Most popular game
+ *
+ * // Get all-time stats (yearly breakdown)
+ * const allTime = await hltb.getGameStats();
+ * console.log(allTime?.years); // { "2020": 1000, "2021": 1200, ... }
  * ```
  *
  * @module

package/script/src/HowLongToBeat.d.ts

@@ -3,7 +3,7 @@
  *
  * Provides methods to search for games on HowLongToBeat.com
  */
-import type { HowLongToBeatEntry, HowLongToBeatOptions } from "./types.js";
+import type { GameStatsOptions, GameStatsResponse, HowLongToBeatEntry, HowLongToBeatOptions } from "./types.js";
 import { SearchModifiers } from "./types.js";
 /**
  * HowLongToBeat API wrapper
@@ -59,5 +59,29 @@ export declare class HowLongToBeat {
      * ```
      */
     searchById(gameId: number): Promise<HowLongToBeatEntry | null>;
+    /**
+     * Get game statistics from HowLongToBeat
+     *
+     * @param options - Optional filters for platform, year, perspective, flow, genre
+     * @returns Game statistics including breakdowns, platform counts, and category rankings
+     *
+     * @example
+     * ```typescript
+     * const hltb = new HowLongToBeat();
+     *
+     * // Get stats for 2026
+     * const stats = await hltb.getGameStats({ year: "2026" });
+     * console.log(stats?.breakdown.totalReleases); // e.g., 771
+     * console.log(stats?.months); // Monthly distribution
+     *
+     * // Get all-time stats (yearly distribution)
+     * const allTime = await hltb.getGameStats();
+     * console.log(allTime?.years); // Yearly distribution
+     *
+     * // Filter by platform
+     * const pcStats = await hltb.getGameStats({ platform: "PC", year: "2026" });
+     * ```
+     */
+    getGameStats(options?: GameStatsOptions): Promise<GameStatsResponse | null>;
 }
 //# sourceMappingURL=HowLongToBeat.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"HowLongToBeat.d.ts","sourceRoot":"","sources":["../../src/src/HowLongToBeat.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAuB7C;;;;;;;;;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;IA+CpE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,YAAY,CAChB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;CAUrC"}

package/script/src/HowLongToBeat.js

@@ -142,5 +142,36 @@ class HowLongToBeat {
         const entries = (0, json_js_1.parseGameEntries)([matchingGame], gameTitle, this.autoFilterTimes, this.similarityCalculator);
         return entries.length > 0 ? entries[0] : null;
     }
+    /**
+     * Get game statistics from HowLongToBeat
+     *
+     * @param options - Optional filters for platform, year, perspective, flow, genre
+     * @returns Game statistics including breakdowns, platform counts, and category rankings
+     *
+     * @example
+     * ```typescript
+     * const hltb = new HowLongToBeat();
+     *
+     * // Get stats for 2026
+     * const stats = await hltb.getGameStats({ year: "2026" });
+     * console.log(stats?.breakdown.totalReleases); // e.g., 771
+     * console.log(stats?.months); // Monthly distribution
+     *
+     * // Get all-time stats (yearly distribution)
+     * const allTime = await hltb.getGameStats();
+     * console.log(allTime?.years); // Yearly distribution
+     *
+     * // Filter by platform
+     * const pcStats = await hltb.getGameStats({ platform: "PC", year: "2026" });
+     * ```
+     */
+    async getGameStats(options = {}) {
+        const response = await (0, client_js_1.fetchGameStats)(options);
+        if (!response) {
+            // TODO: implement proper error handling
+            return null;
+        }
+        return (0, json_js_1.parseGameStats)(response);
+    }
 }
 exports.HowLongToBeat = HowLongToBeat;

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

@@ -1,7 +1,7 @@
 /**
  * HTTP client for HowLongToBeat API
  */
-import type { HLTBSearchRequest, HLTBSearchResponse } from "../types.js";
+import type { GameStatsOptions, GameStatsResponse, HLTBSearchRequest, HLTBSearchResponse } from "../types.js";
 /**
  * Build search request body
  */
@@ -22,6 +22,13 @@ export declare function extractGameTitle(html: string): string | null;
  * Get base URL for constructing image and web links
  */
 export declare function getBaseUrl(): string;
+/**
+ * Fetch game statistics from HLTB API
+ *
+ * @param options - Optional filters for the stats query
+ * @returns Game statistics response, or null on error
+ */
+export declare function fetchGameStats(options?: GameStatsOptions): Promise<GameStatsResponse | null>;
 /**
  * Clear cached token and search URL (useful for testing)
  */

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

@@ -1 +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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/src/http/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAsJrB;;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;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAgCnC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAIjC"}

package/script/src/http/client.js

@@ -8,8 +8,10 @@ exports.executeSearch = executeSearch;
 exports.fetchGamePage = fetchGamePage;
 exports.extractGameTitle = extractGameTitle;
 exports.getBaseUrl = getBaseUrl;
+exports.fetchGameStats = fetchGameStats;
 exports.clearCache = clearCache;
 const HLTB_BASE_URL = "https://howlongtobeat.com";
+const HLTB_STATS_URL = `${HLTB_BASE_URL}/api/stats/games`;
 const HLTB_SEARCH_URL = `${HLTB_BASE_URL}/api/search`;
 const HLTB_GAME_URL = `${HLTB_BASE_URL}/game`;
 /**
@@ -248,6 +250,42 @@ function extractGameTitle(html) {
 function getBaseUrl() {
     return HLTB_BASE_URL;
 }
+/**
+ * Fetch game statistics from HLTB API
+ *
+ * @param options - Optional filters for the stats query
+ * @returns Game statistics response, or null on error
+ */
+async function fetchGameStats(options = {}) {
+    // TODO: Add filter validation for platform, year, perspective, flow, genre
+    const params = new URLSearchParams({
+        platform: options.platform ?? "",
+        year: options.year ?? "",
+        perspective: options.perspective ?? "",
+        flow: options.flow ?? "",
+        genre: options.genre ?? "",
+    });
+    try {
+        const response = await fetch(`${HLTB_STATS_URL}?${params.toString()}`, {
+            method: "GET",
+            headers: {
+                "User-Agent": getRandomUserAgent(),
+                "Referer": HLTB_BASE_URL,
+            },
+        });
+        if (!response.ok) {
+            // TODO: implement proper error handling
+            console.error(`Stats request failed: ${response.status}`);
+            return null;
+        }
+        return await response.json();
+    }
+    catch (error) {
+        // TODO: implement proper error handling
+        console.error("Error fetching game stats:", error);
+        return null;
+    }
+}
 /**
  * Clear cached token and search URL (useful for testing)
  */

package/script/src/parser/json.d.ts

@@ -14,4 +14,15 @@ export declare function parseGameEntries(rawGames: HLTBRawGame[], searchQuery: s
  * Filter entries by minimum similarity threshold
  */
 export declare function filterBySimilarity(entries: HowLongToBeatEntry[], minimumSimilarity: number): HowLongToBeatEntry[];
+import type { GameStatsResponse } from "../types.js";
+/**
+ * Parse game stats response from HLTB API
+ *
+ * Currently passes through the response as-is since the API response
+ * structure matches our type definition.
+ *
+ * @param raw - Raw API response
+ * @returns Parsed game stats response
+ */
+export declare function parseGameStats(raw: GameStatsResponse): GameStatsResponse;
 //# sourceMappingURL=json.d.ts.map

package/script/src/parser/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/src/parser/json.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA2BnE;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,WAAW,EAChB,UAAU,GAAE,MAAU,EACtB,eAAe,GAAE,OAAe,GAC/B,kBAAkB,CAyEpB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,OAAO,EACxB,mBAAmB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,GACpD,kBAAkB,EAAE,CAgBtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAAE,EAC7B,iBAAiB,EAAE,MAAM,GACxB,kBAAkB,EAAE,CAItB"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../../src/src/parser/json.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA2BnE;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,WAAW,EAChB,UAAU,GAAE,MAAU,EACtB,eAAe,GAAE,OAAe,GAC/B,kBAAkB,CAyEpB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,WAAW,EAAE,EACvB,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,OAAO,EACxB,mBAAmB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,GACpD,kBAAkB,EAAE,CAgBtB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,kBAAkB,EAAE,EAC7B,iBAAiB,EAAE,MAAM,GACxB,kBAAkB,EAAE,CAItB;AAED,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,iBAAiB,GACrB,iBAAiB,CAKnB"}

package/script/src/parser/json.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseGameEntry = parseGameEntry;
 exports.parseGameEntries = parseGameEntries;
 exports.filterBySimilarity = filterBySimilarity;
+exports.parseGameStats = parseGameStats;
 const client_js_1 = require("../http/client.js");
 const HLTB_IMAGE_URL = "https://howlongtobeat.com/games";
 /**
@@ -116,3 +117,18 @@ function filterBySimilarity(entries, minimumSimilarity) {
         .filter((entry) => entry.similarity >= minimumSimilarity)
         .sort((a, b) => b.similarity - a.similarity);
 }
+/**
+ * Parse game stats response from HLTB API
+ *
+ * Currently passes through the response as-is since the API response
+ * structure matches our type definition.
+ *
+ * @param raw - Raw API response
+ * @returns Parsed game stats response
+ */
+function parseGameStats(raw) {
+    // The API response structure matches our type definition,
+    // so we pass it through. This function exists for consistency
+    // with other parsers and future transformation needs.
+    return raw;
+}

package/script/src/types.d.ts

@@ -176,4 +176,104 @@ export interface HLTBSearchRequest {
     };
     useCache: boolean;
 }
+/**
+ * Options for filtering game statistics
+ */
+export interface GameStatsOptions {
+    /** Filter by platform (e.g., "PC", "PlayStation 5") */
+    platform?: string;
+    /** Filter by year (e.g., "2026"). If omitted, returns yearly aggregates instead of monthly */
+    year?: string;
+    /** Filter by perspective (e.g., "First-Person", "Third-Person") */
+    perspective?: string;
+    /** Filter by flow/pacing */
+    flow?: string;
+    /** Filter by genre */
+    genre?: string;
+}
+/**
+ * Tags/filters applied to the stats query
+ */
+export interface StatsTags {
+    genres: string;
+    platform: string;
+    year: string;
+}
+/**
+ * Breakdown statistics for the filtered games
+ */
+export interface StatsBreakdown {
+    /** Total number of game releases */
+    totalReleases: number;
+    /** Average completion time (formatted string like "14h 8m") */
+    avgTime: string;
+    /** Average review rating (0-100) */
+    avgRating: number;
+    /** Number of playthroughs */
+    playthroughs: string;
+}
+/**
+ * Platform count entry
+ */
+export interface PlatformCount {
+    platform: string;
+    count_total: number;
+}
+/**
+ * Category entry for various rankings (most backlogged, completed, etc.)
+ */
+export interface CategoryEntry {
+    game_id: number;
+    game_name: string;
+    stat: number;
+}
+/**
+ * Popular game entry with additional metadata
+ */
+export interface PopularGameEntry {
+    id: number;
+    title: string;
+    platform: string;
+    class: string;
+    /** Release date in "YYYY-MM-DD" format */
+    stats: string;
+    popular: number;
+}
+/**
+ * Game statistics response from HLTB API
+ */
+export interface GameStatsResponse {
+    /** Applied filter tags */
+    tags: StatsTags;
+    /** Summary breakdown statistics */
+    breakdown: StatsBreakdown;
+    /** Monthly distribution (keys "00"-"12", present when year is specified) */
+    months?: Record<string, number>;
+    /** Yearly distribution (present when year is not specified) */
+    years?: Record<string, number>;
+    /** Games per platform */
+    platformList: PlatformCount[];
+    /** Games with most backlog entries */
+    categoryMostBacklogged: CategoryEntry[];
+    /** Games with most speedruns */
+    categoryMostSpeedruns: CategoryEntry[];
+    /** Games with most completions */
+    categoryMostCompleted: CategoryEntry[];
+    /** Games with most retired/dropped entries */
+    categoryMostRetired: CategoryEntry[];
+    /** Highest rated games */
+    categoryBestRated: CategoryEntry[];
+    /** Lowest rated games */
+    categoryWorstRated: CategoryEntry[];
+    /** Games currently being played the most */
+    categoryTopPlaying: CategoryEntry[];
+    /** Most reviewed games */
+    categoryMostReviews: CategoryEntry[];
+    /** Longest games by completion time */
+    categoryLongestGames: CategoryEntry[];
+    /** Shortest games by completion time */
+    categoryShortestGames: CategoryEntry[];
+    /** Currently popular games */
+    popularGames: PopularGameEntry[];
+}
 //# sourceMappingURL=types.d.ts.map

package/script/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/src/types.ts"],"names":[],"mappings":"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"}