itchlib 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0
+
+- Game info: `getGame`, `getUploads`, `getComments`, `getProfile`.
+- Discovery: `searchGames`, `getSuggestions`, `getBrowsePage`, `getFeed`.
+- Downloads: `getDownloadUploads`, `getDownloadUrl`.
+- Authenticated API: profile, games, ownership, purchases, rewards, keys, collections, and latest-version helpers.
+- Developer tools: reusable `ItchClient`, TypeScript types, request retries, and cancellation with `AbortSignal`.

package/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Thanks for helping improve itchlib!
+
+## Development
+
+Use Node.js 22.19 or later.
+
+Install dependencies:
+
+```bash
+npm ci
+```
+
+Before opening a pull request, run:
+
+```bash
+npm run check
+npm run typecheck
+npm run pack:check
+```
+
+### Guidelines
+
+- When itch.io changes its page structure, update only the affected parser.
+- Preserve original site data where possible instead of inventing classifications.
+
+## Pull Requests
+
+Describe what your changes do, any public API changes, and which checks you ran.
+
+Never include real credentials, cookies, purchase keys, or private download URLs in logs.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 Neutralinojs and contributors
+Copyright (c) 2026 itchlib contributors
+
+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

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# itchlib
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Node.js library for exploring itch.io games, creators, downloads, and more stuff.
+
+## Requirements
+
+- Node.js 22.19 or later
+- Also ESM support
+
+## Installation
+
+```bash
+npm install itchlib
+```
+
+## Quick start
+
+```js
+import { ItchClient } from "itchlib";
+
+const itch = new ItchClient();
+const game = await itch.getGame("https://ninja-muffin24.itch.io/funkin");
+// heh,, Friday Night Funkin'
+
+console.log(game.title);
+console.log(game.descriptionHtml);
+console.log(game.images);
+console.log(game.uploads);
+```
+
+`getGame()` returns information available on the game's itch.io page, including its description, media, links, details, downloads, and comments.
+
+Documentation is WIP still so wait a bit for that :)

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes target the latest release of itchlib.
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities through GitHub's private vulnerability reporting feature, if enabled. Avoid disclosing vulnerabilities in public issues.
+
+Never include API keys, access tokens, purchase keys, cookies, or private download URLs in public reports or logs. If credentials have been exposed, revoke or rotate them before sharing diagnostics.
+
+## Credential Handling
+
+Authenticated API requests send bearer tokens only to `https://api.itch.io`. itchlib does not intentionally log credentials or response bodies.

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "itchlib",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "A Node.js client for reading itch.io games, creators, search, community, and downloads.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/immalloy/itchlib.git"
+  },
+  "homepage": "https://github.com/immalloy/itchlib#readme",
+  "bugs": {
+    "url": "https://github.com/immalloy/itchlib/issues"
+  },
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "check": "node --check src/index.js && npm run format:check && npm run lint",
+    "typecheck": "tsc --project tsconfig.json",
+    "pack:check": "npm pack --dry-run",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint ."
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src/",
+    "types/",
+    "README.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "keywords": [
+    "itch.io",
+    "itchio",
+    "games",
+    "game-discovery",
+    "metadata",
+    "downloads",
+    "scraper"
+  ],
+  "dependencies": {
+    "cheerio": "^1.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.14.0",
+    "globals": "^17.14.0",
+    "prettier": "^3.10.0",
+    "typescript": "^7.0.2"
+  },
+  "overrides": {
+    "minimatch": "^11.0.8"
+  }
+}

package/src/api.js

@@ -0,0 +1,267 @@
+import { ItchError, readJson } from "./errors.js";
+
+async function parseApiResponse(response, endpoint, invalidJsonMessage, failureMessage) {
+  if (!response.ok) {
+    let result = null;
+    try {
+      result = await response.clone().json();
+    } catch {
+      // Some edge and rate-limit responses are HTML, even for JSON endpoints.
+    }
+    throw new ItchError(result?.errors?.join("; ") || `${failureMessage} (HTTP ${response.status})`, {
+      status: response.status,
+      url: endpoint.href,
+      code: "ITCH_HTTP_ERROR",
+    });
+  }
+  const result = await readJson(response, invalidJsonMessage, endpoint);
+  if (result?.errors?.length) {
+    throw new ItchError(result.errors.join("; "), {
+      status: response.status,
+      url: endpoint.href,
+      code: "ITCH_API_ERROR",
+    });
+  }
+  return result;
+}
+
+export async function apiRequest(client, path, { query, method = "GET", body, headers = {}, signal } = {}) {
+  if (!client.apiKey)
+    throw new ItchError("An itch.io API key is required for this method", { code: "ITCH_AUTH_REQUIRED" });
+  const endpoint = new URL(String(path).replace(/^\//, ""), "https://api.itch.io/");
+  if (endpoint.hostname !== "api.itch.io" || endpoint.protocol !== "https:") {
+    throw new ItchError("API requests must target api.itch.io", {
+      url: endpoint.href,
+      code: "ITCH_INVALID_URL",
+    });
+  }
+  for (const [key, value] of Object.entries(query || {})) {
+    if (value !== undefined && value !== null)
+      endpoint.searchParams.set(key, Array.isArray(value) ? value.join(",") : String(value));
+  }
+  const requestHeaders = { Authorization: `Bearer ${client.apiKey}`, Accept: "application/json", ...headers };
+  const requestOptions = { method, headers: requestHeaders, ...(signal ? { signal } : {}) };
+  if (body !== undefined) {
+    requestOptions.body = new URLSearchParams(
+      Object.entries(body)
+        .filter(([, value]) => value !== undefined && value !== null)
+        .map(([key, value]) => [key, String(value)]),
+    );
+    requestHeaders["Content-Type"] = "application/x-www-form-urlencoded";
+  }
+  const response = await client.request(endpoint, requestOptions);
+  return parseApiResponse(response, endpoint, "Itch.io API returned invalid JSON", "Itch.io API failed");
+}
+
+export function getLatestVersion(client, { channelName, target, gameId, signal } = {}) {
+  if (!channelName || (!target && !gameId) || (target && gameId)) {
+    throw new TypeError("Provide channelName and exactly one of target or gameId");
+  }
+  if (gameId !== undefined) validateApiId(gameId, "gameId");
+  const endpoint = new URL("https://api.itch.io/wharf/latest");
+  endpoint.searchParams.set("channel_name", channelName);
+  if (target) endpoint.searchParams.set("target", target);
+  if (gameId) endpoint.searchParams.set("game_id", String(gameId));
+  return client
+    .request(endpoint, { ...(signal ? { signal } : {}), headers: { Accept: "application/json" } })
+    .then((response) =>
+      parseApiResponse(
+        response,
+        endpoint,
+        "Itch.io version endpoint returned invalid JSON",
+        "Itch.io version request failed",
+      ),
+    );
+}
+
+export async function getAllOwnedKeys(client, { perPage = 500, gameIds, signal } = {}) {
+  validatePage(perPage, "perPage", 500);
+  validateGameIds(gameIds);
+  const keys = [];
+  for (let page = 1; ; page += 1) {
+    const result = await apiRequest(client, "profile/owned-keys", {
+      query: { page, per_page: perPage, game_ids: gameIds },
+      signal,
+    });
+    const current = result.owned_keys || [];
+    keys.push(...current);
+    if (!current.length) return keys;
+  }
+}
+
+function validatePage(page, name, maximum = Number.MAX_SAFE_INTEGER) {
+  if (!Number.isSafeInteger(page) || page < 1 || page > maximum) {
+    throw new TypeError(`${name} must be an integer between 1 and ${maximum}`);
+  }
+}
+
+export function validateApiId(id, name) {
+  if (!/^\d+$/.test(String(id ?? ""))) throw new TypeError(`${name} must be a numeric itch.io ID`);
+}
+
+export function validateGameIds(gameIds) {
+  if (gameIds !== undefined && (!Array.isArray(gameIds) || gameIds.length > 50)) {
+    throw new TypeError("gameIds must be an array with no more than 50 IDs");
+  }
+  for (const gameId of gameIds || []) validateApiId(gameId, "gameId");
+}
+
+export function getApiCredentials(client, options) {
+  return apiRequest(client, "credentials/info", options);
+}
+
+export function getGameDownloadKey(client, gameId, { downloadKey, userId, email, signal } = {}) {
+  validateApiId(gameId, "gameId");
+  const identifiers = [downloadKey, userId, email].filter(
+    (value) => value !== undefined && value !== null && value !== "",
+  );
+  if (identifiers.length !== 1) {
+    throw new TypeError("Provide exactly one of downloadKey, userId, or email");
+  }
+  return apiRequest(client, `games/${encodeURIComponent(gameId)}/download_keys`, {
+    query: { download_key: downloadKey, user_id: userId, email },
+    signal,
+  });
+}
+
+export function getGamePurchases(client, gameId, { userId, email, signal } = {}) {
+  validateApiId(gameId, "gameId");
+  if (
+    (userId === undefined || userId === null || userId === "") ===
+    (email === undefined || email === null || email === "")
+  ) {
+    throw new TypeError("Provide exactly one of userId or email");
+  }
+  return apiRequest(client, `games/${encodeURIComponent(gameId)}/purchases`, {
+    query: { user_id: userId, email },
+    signal,
+  });
+}
+
+export function getClaimedRewards(client, gameId, { page = 1, signal } = {}) {
+  validateApiId(gameId, "gameId");
+  validatePage(page, "page");
+  return apiRequest(client, `games/${encodeURIComponent(gameId)}/claimed-rewards`, {
+    query: { page },
+    signal,
+  });
+}
+
+export async function getAllClaimedRewards(client, gameId, { signal } = {}) {
+  validateApiId(gameId, "gameId");
+  const rewards = [];
+  for (let page = 1; ; page += 1) {
+    const result = await getClaimedRewards(client, gameId, { page, signal });
+    const current = result.claimed_rewards || [];
+    rewards.push(...current);
+    if (!current.length) return rewards;
+  }
+}
+
+export function checkGameOwnership(client, gameId, options) {
+  validateApiId(gameId, "gameId");
+  return apiRequest(client, `games/${encodeURIComponent(gameId)}/ownership`, options);
+}
+
+export function getCollections(client, { gameId, signal } = {}) {
+  if (gameId !== undefined && gameId !== null) validateApiId(gameId, "gameId");
+  return apiRequest(client, "profile/collections", { query: { game_id: gameId }, signal });
+}
+
+export function getCollection(client, collectionId, options) {
+  validateApiId(collectionId, "collectionId");
+  return apiRequest(client, `collections/${encodeURIComponent(collectionId)}`, options);
+}
+
+export function getCollectionGames(client, collectionId, { page = 1, perPage = 100, signal } = {}) {
+  validateApiId(collectionId, "collectionId");
+  validatePage(page, "page");
+  validatePage(perPage, "perPage", 500);
+  return apiRequest(client, `collections/${encodeURIComponent(collectionId)}/collection-games`, {
+    query: { page, per_page: perPage },
+    signal,
+  });
+}
+
+export async function getAllCollectionGames(client, collectionId, { perPage = 100, signal } = {}) {
+  validateApiId(collectionId, "collectionId");
+  validatePage(perPage, "perPage", 500);
+  const games = [];
+  for (let page = 1; ; page += 1) {
+    const result = await getCollectionGames(client, collectionId, { page, perPage, signal });
+    const current = result.collection_games || [];
+    games.push(...current);
+    if (!current.length) return games;
+  }
+}
+
+export function createCollection(client, collection, { signal } = {}) {
+  return apiRequest(client, "collections", { method: "POST", body: collection, signal });
+}
+
+export function updateCollection(client, collectionId, collection, { signal } = {}) {
+  validateApiId(collectionId, "collectionId");
+  return apiRequest(client, `collections/${encodeURIComponent(collectionId)}`, {
+    method: "POST",
+    body: collection,
+    signal,
+  });
+}
+
+export function deleteCollection(client, collectionId, options) {
+  validateApiId(collectionId, "collectionId");
+  return apiRequest(client, `collections/${encodeURIComponent(collectionId)}/delete`, {
+    method: "POST",
+    ...options,
+  });
+}
+
+export function addGameToCollection(client, collectionId, { gameId, blurb }, { signal } = {}) {
+  validateApiId(collectionId, "collectionId");
+  validateApiId(gameId, "gameId");
+  return apiRequest(client, `collections/${encodeURIComponent(collectionId)}/add-game`, {
+    method: "POST",
+    body: { game_id: gameId, blurb },
+    signal,
+  });
+}
+
+export function removeGameFromCollection(client, collectionId, gameId, { signal } = {}) {
+  validateApiId(collectionId, "collectionId");
+  validateApiId(gameId, "gameId");
+  return apiRequest(client, `collections/${encodeURIComponent(collectionId)}/remove-game`, {
+    method: "POST",
+    body: { game_id: gameId },
+    signal,
+  });
+}
+
+export function updateCollectionGame(client, collectionId, gameId, { blurb }, { signal } = {}) {
+  validateApiId(collectionId, "collectionId");
+  validateApiId(gameId, "gameId");
+  return apiRequest(
+    client,
+    `collections/${encodeURIComponent(collectionId)}/collection-games/${encodeURIComponent(gameId)}`,
+    { method: "POST", body: { blurb }, signal },
+  );
+}
+
+export function orderCollection(client, collectionId, { gameIds, removeGameIds }, { signal } = {}) {
+  validateApiId(collectionId, "collectionId");
+  if (!Array.isArray(gameIds) || gameIds.length > 500) {
+    throw new TypeError("gameIds must be an array with no more than 500 IDs");
+  }
+  if (removeGameIds !== undefined && (!Array.isArray(removeGameIds) || removeGameIds.length > 500)) {
+    throw new TypeError("removeGameIds must be an array with no more than 500 IDs");
+  }
+  for (const gameId of gameIds) validateApiId(gameId, "gameId");
+  for (const gameId of removeGameIds || []) validateApiId(gameId, "gameId");
+  return apiRequest(client, `collections/${encodeURIComponent(collectionId)}/order`, {
+    method: "POST",
+    body: {
+      game_ids: JSON.stringify(gameIds),
+      remove_game_ids: removeGameIds === undefined ? undefined : JSON.stringify(removeGameIds),
+    },
+    signal,
+  });
+}

package/src/client.js

@@ -0,0 +1,231 @@
+import * as api from "./api.js";
+import { getDownloadUploads, getDownloadUrl } from "./downloads.js";
+import { ItchError, assertResponse, readJson } from "./errors.js";
+import { ItchTransport } from "./http.js";
+import { parseBrowsePage } from "./parsers/browse.js";
+import { parseFeed } from "./parsers/feed.js";
+import { parseGame } from "./parsers/game.js";
+import { parseProfile } from "./parsers/profile.js";
+import { ITCH_BROWSE_PAGES } from "./routes.js";
+import { assertItchUrl, normalizeProfileUrl, validateGameUrl } from "./urls.js";
+
+const FEEDS = Object.freeze({
+  new: "https://itch.io/feed/new.xml",
+  featured: "https://itch.io/feed/featured.xml",
+  sales: "https://itch.io/feed/sales.xml",
+});
+
+export class ItchClient {
+  constructor(options = {}) {
+    const { apiKey, accessToken, token, ...transportOptions } = options;
+    this.apiKey = accessToken || token || apiKey;
+    this.transport = new ItchTransport(transportOptions);
+  }
+
+  request(url, options) {
+    return this.transport.request(url, options);
+  }
+
+  async getGame(gameValue, { signal } = {}) {
+    const url = validateGameUrl(gameValue);
+    const response = assertResponse(await this.request(url, { signal }), "Itch.io game page failed", url);
+    return parseGame(await response.text(), response.url || url.href);
+  }
+
+  async getUploads(gameUrl, options) {
+    return (await this.getGame(gameUrl, options)).uploads;
+  }
+
+  getDownloadUploads(gameUrl, options) {
+    return getDownloadUploads(this, gameUrl, options);
+  }
+
+  getDownloadUrl(gameUrl, uploadId, options) {
+    return getDownloadUrl(this, gameUrl, uploadId, options);
+  }
+
+  async getComments(gameUrl, options) {
+    return (await this.getGame(gameUrl, options)).comments;
+  }
+
+  async getProfile(profile, { signal } = {}) {
+    const url = normalizeProfileUrl(profile);
+    const response = assertResponse(await this.request(url, { signal }), "Itch.io profile page failed", url);
+    return parseProfile(await response.text(), response.url || url.href);
+  }
+
+  async getBrowsePage(section = "games", { query, page, params = {}, signal } = {}) {
+    const route = ITCH_BROWSE_PAGES[section] || section;
+    let url;
+    try {
+      url = /^https:\/\//i.test(route) ? new URL(route) : new URL(route, "https://itch.io");
+    } catch (cause) {
+      throw new ItchError("Expected a valid itch.io route or URL", { code: "ITCH_INVALID_URL", cause });
+    }
+    assertItchUrl(url, { allowSubdomains: false });
+    if (query !== undefined && query !== null) url.searchParams.set("q", String(query));
+    if (page !== undefined && page !== null) url.searchParams.set("page", String(page));
+    for (const [key, value] of Object.entries(params)) {
+      if (value === undefined || value === null) continue;
+      url.searchParams.delete(key);
+      for (const item of Array.isArray(value) ? value : [value]) url.searchParams.append(key, String(item));
+    }
+    const response = assertResponse(
+      await this.request(url, { signal }),
+      "Itch.io browse request failed",
+      url,
+    );
+    return parseBrowsePage(await response.text(), url.href);
+  }
+
+  searchGames(query, { page = 1, signal, ...params } = {}) {
+    return this.getBrowsePage("search", { query, page, params, signal });
+  }
+
+  async getSuggestions(query, { signal } = {}) {
+    const url = new URL("https://itch.io/autocomplete");
+    url.searchParams.set("query", String(query));
+    const response = assertResponse(
+      await this.request(url, { signal, headers: { Accept: "application/json" } }),
+      "Itch.io suggestions request failed",
+      url,
+    );
+    return readJson(response, "Itch.io suggestions returned invalid JSON", url);
+  }
+
+  async getFeed(feed = "new", { signal } = {}) {
+    let url;
+    try {
+      const browseRoute = ITCH_BROWSE_PAGES[feed];
+      const source = FEEDS[feed] || (browseRoute ? `${browseRoute}.xml` : feed);
+      url = /^https:\/\//i.test(source) ? new URL(source) : new URL(source, "https://itch.io");
+    } catch (cause) {
+      throw new ItchError("Expected an itch.io feed name or URL", { code: "ITCH_INVALID_URL", cause });
+    }
+    assertItchUrl(url);
+    if (!url.pathname.endsWith(".xml"))
+      throw new ItchError("Expected an itch.io RSS feed URL ending in .xml", {
+        url: url.href,
+        code: "ITCH_INVALID_URL",
+      });
+    const response = assertResponse(
+      await this.request(url, {
+        signal,
+        headers: { Accept: "application/rss+xml, application/xml, text/xml" },
+      }),
+      "Itch.io feed request failed",
+      url,
+    );
+    return parseFeed(await response.text(), feed, url.href);
+  }
+
+  apiRequest(path, options) {
+    return api.apiRequest(this, path, options);
+  }
+
+  getApiCredentials(options) {
+    return api.getApiCredentials(this, options);
+  }
+
+  getApiProfile(options) {
+    return this.apiRequest("profile", options);
+  }
+
+  getDeveloperGames(options) {
+    return this.apiRequest("profile/games", options);
+  }
+
+  getApiUploads(gameId, options) {
+    api.validateApiId(gameId, "gameId");
+    return this.apiRequest(`games/${encodeURIComponent(gameId)}/uploads`, options);
+  }
+
+  getApiDownloadUrl(uploadId, options) {
+    api.validateApiId(uploadId, "uploadId");
+    return this.apiRequest(`uploads/${encodeURIComponent(uploadId)}/download`, options);
+  }
+
+  getGameDownloadKey(gameId, options) {
+    return api.getGameDownloadKey(this, gameId, options);
+  }
+
+  getGamePurchases(gameId, options) {
+    return api.getGamePurchases(this, gameId, options);
+  }
+
+  getClaimedRewards(gameId, options) {
+    return api.getClaimedRewards(this, gameId, options);
+  }
+
+  getAllClaimedRewards(gameId, options) {
+    return api.getAllClaimedRewards(this, gameId, options);
+  }
+
+  checkGameOwnership(gameId, options) {
+    return api.checkGameOwnership(this, gameId, options);
+  }
+
+  getCollections(options) {
+    return api.getCollections(this, options);
+  }
+
+  getCollection(collectionId, options) {
+    return api.getCollection(this, collectionId, options);
+  }
+
+  getCollectionGames(collectionId, options) {
+    return api.getCollectionGames(this, collectionId, options);
+  }
+
+  getAllCollectionGames(collectionId, options) {
+    return api.getAllCollectionGames(this, collectionId, options);
+  }
+
+  createCollection(collection, options) {
+    return api.createCollection(this, collection, options);
+  }
+
+  updateCollection(collectionId, collection, options) {
+    return api.updateCollection(this, collectionId, collection, options);
+  }
+
+  deleteCollection(collectionId, options) {
+    return api.deleteCollection(this, collectionId, options);
+  }
+
+  addGameToCollection(collectionId, game, options) {
+    return api.addGameToCollection(this, collectionId, game, options);
+  }
+
+  removeGameFromCollection(collectionId, gameId, options) {
+    return api.removeGameFromCollection(this, collectionId, gameId, options);
+  }
+
+  updateCollectionGame(collectionId, gameId, game, options) {
+    return api.updateCollectionGame(this, collectionId, gameId, game, options);
+  }
+
+  orderCollection(collectionId, order, options) {
+    return api.orderCollection(this, collectionId, order, options);
+  }
+
+  getLatestVersion(options) {
+    return api.getLatestVersion(this, options);
+  }
+
+  getOwnedKeys({ page = 1, perPage = 500, gameIds, ...options } = {}) {
+    if (!Number.isSafeInteger(page) || page < 1) throw new TypeError("page must be a positive integer");
+    if (!Number.isSafeInteger(perPage) || perPage < 1 || perPage > 500) {
+      throw new TypeError("perPage must be an integer between 1 and 500");
+    }
+    api.validateGameIds(gameIds);
+    return this.apiRequest("profile/owned-keys", {
+      query: { page, per_page: perPage, game_ids: gameIds },
+      ...options,
+    });
+  }
+
+  getAllOwnedKeys(options) {
+    return api.getAllOwnedKeys(this, options);
+  }
+}