@irrg/itchio-hoard 0.1.0

package/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Robb Irrgang
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,62 @@
+# itchio-hoard
+
+TypeScript port of [irrg/itchio](https://github.com/irrg/itchio). Downloads your itch.io library.
+
+## Install
+
+```bash
+pnpm install
+```
+
+## CLI
+
+```bash
+# download full library
+pnpm itchio-hoard -- -k YOUR_API_KEY
+
+# with concurrency (max 8)
+pnpm itchio-hoard -- -k YOUR_API_KEY -j 4
+
+# platform filter: windows, linux, osx, android
+pnpm itchio-hoard -- -k YOUR_API_KEY -p osx
+
+# use display names for folder structure instead of URL slugs
+pnpm itchio-hoard -- -k YOUR_API_KEY --human-folders
+```
+
+Get an API key at https://itch.io/user/settings/api-keys.
+
+Failed downloads are logged to `errors.txt` in the working directory.
+
+## Library
+
+```typescript
+import { Library } from './src/index.js';
+
+const lib = new Library(apiKey, 4);
+await lib.loadOwnedGames(); // lib.games: Game[]
+
+// download everything
+await lib.downloadLibrary('osx'); // platform optional
+
+// or one game at a time
+const game = lib.games[0];
+await game.loadDownloads(apiKey); // game.downloads: Upload[]
+await game.doDownload(game.downloads[0], apiKey);
+```
+
+## See also
+
+Part of the hoard family — [humblebundle-hoard](https://github.com/irrg/humblebundle-hoard), [drivethru-hoard](https://github.com/irrg/drivethru-hoard), [bundleofholding-hoard](https://github.com/irrg/bundleofholding-hoard).
+
+## License
+
+Copyright (c) 2026, Robb Irrgang
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/bin/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/index.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { intro, text, password, outro, isCancel, cancel } from '@clack/prompts';
+import { loginAPI, Library } from '../src/index.js';
+const argv = process.argv.slice(2);
+const { values: args } = parseArgs({
+    args: argv[0] === '--' ? argv.slice(1) : argv,
+    options: {
+        key: { type: 'string', short: 'k' },
+        platform: { type: 'string', short: 'p' },
+        human: { type: 'boolean' },
+        jobs: { type: 'string', short: 'j' },
+        collections: { type: 'boolean' },
+        collection: { type: 'string', short: 'c' },
+        bundles: { type: 'boolean' },
+        bundle: { type: 'string', short: 'b' },
+        output: { type: 'string', short: 'o' },
+        filter: { type: 'string', short: 'f', multiple: true },
+        'dry-run': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+    },
+    strict: true,
+});
+if (args.help) {
+    console.log(`Usage: itchio-hoard [options]
+
+Options:
+  -k, --key <key>          API key (prompts for credentials if omitted)
+  -p, --platform <name>    Filter by platform: windows, linux, osx, android
+      --human              Use game titles for folder names instead of URL slugs
+  -j, --jobs <n>           Concurrent downloads (default: 4, max: 8)
+      --collections        List your itch.io collections and exit
+  -c, --collection <id>    Download all games in a collection by ID
+      --bundles            List your purchased bundles and exit
+  -b, --bundle <id>        Download all games in a bundle by ID
+  -o, --output <dir>       Output directory (default: downloads)
+  -f, --filter <term>      Filter games by name (case-insensitive substring); repeat for multiple
+      --dry-run            Show what would be downloaded without downloading
+  -h, --help               Show this help`);
+    process.exit(0);
+}
+let token = args.key ?? '';
+if (!token) {
+    intro('itchcraft');
+    const user = await text({ message: 'Username:' });
+    if (isCancel(user)) {
+        cancel();
+        process.exit(1);
+    }
+    const pass = await password({ message: 'Password:' });
+    if (isCancel(pass)) {
+        cancel();
+        process.exit(1);
+    }
+    token = await loginAPI(user, pass);
+}
+const jobs = args.jobs != null ? parseInt(args.jobs, 10) : 4;
+if (isNaN(jobs) || jobs < 1) {
+    console.error(`Invalid --jobs value: "${args.jobs}". Must be a positive integer.`);
+    process.exit(1);
+}
+const lib = new Library(token, jobs, args.human ?? false, args.output ?? 'downloads', args['dry-run'] ?? false, args.filter ?? []);
+if (args.collections) {
+    const profile = await lib.getProfile();
+    if (profile) {
+        console.log(`Profile: ${profile.display_name ?? profile.username}`);
+    }
+    const collections = await lib.loadCollections();
+    if (collections.length === 0) {
+        console.log('No collections found.');
+    }
+    else {
+        for (const c of collections) {
+            console.log(`  [${c.id}] ${c.title} (${c.games_count ?? '?'} games)`);
+        }
+    }
+    process.exit(0);
+}
+if (args.collection != null) {
+    const collectionId = parseInt(args.collection, 10);
+    if (isNaN(collectionId) || collectionId < 1) {
+        console.error(`Invalid --collection value: "${args.collection}". Must be a positive integer.`);
+        process.exit(1);
+    }
+    await lib.loadCollection(collectionId);
+    await lib.downloadLibrary(args.platform);
+    outro('Done.');
+    process.exit(0);
+}
+if (args.bundles) {
+    const profile = await lib.getProfile();
+    if (profile) {
+        console.log(`Profile: ${profile.display_name ?? profile.username}`);
+    }
+    const bundles = await lib.loadBundles();
+    if (bundles.length === 0) {
+        console.log('No bundles found.');
+    }
+    else {
+        for (const bk of bundles) {
+            console.log(`  [${bk.bundle.id}] ${bk.bundle.title} (${bk.bundle.games_count ?? '?'} games)`);
+        }
+    }
+    process.exit(0);
+}
+if (args.bundle != null) {
+    const bundleId = parseInt(args.bundle, 10);
+    if (isNaN(bundleId) || bundleId < 1) {
+        console.error(`Invalid --bundle value: "${args.bundle}". Must be a positive integer.`);
+        process.exit(1);
+    }
+    await lib.loadBundle(bundleId);
+    await lib.downloadLibrary(args.platform);
+    outro('Done.');
+    process.exit(0);
+}
+await lib.loadOwnedGames();
+await lib.downloadLibrary(args.platform);
+outro('Done.');

package/dist/src/game.d.ts

@@ -0,0 +1,43 @@
+export interface GameData {
+    title: string;
+    user?: {
+        username: string;
+        display_name?: string;
+    };
+    url: string;
+    id: number;
+    [key: string]: unknown;
+}
+export interface OwnedKeyData {
+    id?: number;
+    game_id?: number;
+    game: GameData;
+    [key: string]: unknown;
+}
+export interface Upload {
+    id: number;
+    filename?: string;
+    display_name?: string;
+    traits?: string[];
+    md5_hash?: string;
+    [key: string]: unknown;
+}
+export declare class Game {
+    data: GameData;
+    name: string;
+    publisher: string;
+    link: string;
+    id: number | false;
+    gameId: number;
+    gameSlug: string;
+    publisherSlug: string;
+    dir: string;
+    outputDir: string;
+    downloads: Upload[];
+    dryRun: boolean;
+    constructor(data: OwnedKeyData, humanFolders?: boolean, outputDir?: string, dryRun?: boolean);
+    loadDownloads(token: string): Promise<void>;
+    download(token: string, platform?: string): Promise<void>;
+    doDownload(d: Upload, token: string): Promise<boolean>;
+    private _logError;
+}

package/dist/src/game.js

@@ -0,0 +1,197 @@
+import { existsSync } from 'fs';
+import { writeFile, readFile, mkdir, rename, appendFile } from 'fs/promises';
+import path from 'path';
+import { cleanPath, download, fetchWithRetry, md5sum, NoDownloadError } from './utils.js';
+export class Game {
+    data;
+    name;
+    publisher;
+    link;
+    id;
+    gameId;
+    gameSlug;
+    publisherSlug;
+    dir;
+    outputDir;
+    downloads;
+    dryRun;
+    constructor(data, humanFolders = false, outputDir = 'downloads', dryRun = false) {
+        this.data = data.game;
+        this.name = this.data.title;
+        this.link = this.data.url;
+        const matches = this.link.match(/https:\/\/(.+)\.itch\.io\/(.+)/);
+        if (!matches)
+            throw new Error(`Cannot parse game URL: ${this.link}`);
+        this.publisher = this.data.user?.username ?? matches[1];
+        if ('game_id' in data && data.game_id != null) {
+            this.id = data.id;
+            this.gameId = data.game_id;
+        }
+        else {
+            this.id = false;
+            this.gameId = this.data.id;
+        }
+        if (humanFolders) {
+            this.gameSlug = cleanPath(this.data.title);
+            this.publisherSlug = cleanPath(this.data.user?.display_name ?? this.data.user?.username ?? matches[1]);
+        }
+        else {
+            this.publisherSlug = matches[1];
+            this.gameSlug = matches[2];
+        }
+        this.outputDir = outputDir;
+        this.dir = path.join(outputDir, cleanPath(this.publisherSlug), cleanPath(this.gameSlug));
+        this.downloads = [];
+        this.dryRun = dryRun;
+    }
+    async loadDownloads(token) {
+        this.downloads = [];
+        const url = this.id
+            ? `https://api.itch.io/games/${this.gameId}/uploads?download_key_id=${this.id}`
+            : `https://api.itch.io/games/${this.gameId}/uploads`;
+        const r = await fetchWithRetry(url, { headers: { Authorization: token } });
+        let j;
+        try {
+            j = (await r.json());
+        }
+        catch {
+            console.log(`Failed to load downloads for ${this.name} (HTTP ${r.status}), skipping`);
+            return;
+        }
+        this.downloads = Array.isArray(j.uploads) ? j.uploads : [];
+    }
+    async download(token, platform) {
+        console.log('Downloading', this.name);
+        await this.loadDownloads(token);
+        const eligible = this.downloads.filter((d) => {
+            if (platform != null && Array.isArray(d.traits)) {
+                const platformTraits = d.traits.filter((t) => t.startsWith('p_'));
+                if (platformTraits.length > 0 && !platformTraits.includes(`p_${platform}`)) {
+                    console.log(`Skipping ${this.name} - ${d.filename ?? d.id} (${platformTraits.join(', ')})`);
+                    return false;
+                }
+            }
+            return true;
+        });
+        if (eligible.length === 0)
+            return;
+        await mkdir(this.dir, { recursive: true });
+        let wrote = 0;
+        for (const d of eligible) {
+            if (await this.doDownload(d, token))
+                wrote++;
+        }
+        if (wrote === 0)
+            return;
+        const manifestPath = this.dir + '.json';
+        await writeFile(manifestPath, JSON.stringify({
+            name: this.name,
+            publisher: this.publisher,
+            link: this.link,
+            itch_id: this.id,
+            game_id: this.gameId,
+            itch_data: this.data,
+        }, null, 2));
+    }
+    async doDownload(d, token) {
+        const rawFilename = d.filename ?? d.display_name ?? String(d.id);
+        const filename = cleanPath(rawFilename);
+        const outFile = path.join(this.dir, filename);
+        const md5Hash = d.md5_hash;
+        if (this.dryRun) {
+            console.log(`Dry run: ${this.name} - ${filename}`);
+            return false;
+        }
+        console.log(`Downloading ${filename}`);
+        if (existsSync(outFile)) {
+            console.log(`File already exists: ${filename}`);
+            if (!md5Hash) {
+                console.log(`Skipping ${this.name} - ${filename}`);
+                return true;
+            }
+            const md5File = withSuffix(outFile, '.md5');
+            if (existsSync(md5File)) {
+                const storedMd5 = (await readFile(md5File, 'utf8')).trim();
+                if (storedMd5 === md5Hash) {
+                    console.log(`Skipping ${this.name} - ${filename}`);
+                    return true;
+                }
+                console.log(`Checksum mismatch: ${filename}`);
+            }
+            else {
+                const computed = await md5sum(outFile);
+                if (computed === md5Hash) {
+                    console.log(`Skipping ${this.name} - ${filename}`);
+                    await writeFile(md5File, md5Hash);
+                    return true;
+                }
+            }
+            const oldDir = path.join(this.dir, 'old');
+            await mkdir(oldDir, { recursive: true });
+            console.log(`Moving ${filename} to old/`);
+            const timestamp = new Date().toISOString().split('T')[0];
+            await rename(outFile, path.join(oldDir, `${timestamp}-${filename}`));
+        }
+        // Get download session UUID
+        const sessionResp = await fetchWithRetry(`https://api.itch.io/games/${this.gameId}/download-sessions`, {
+            method: 'POST',
+            headers: { Authorization: token },
+        });
+        let sessionJson;
+        try {
+            sessionJson = (await sessionResp.json());
+        }
+        catch {
+            console.log(`Failed to start download session for ${this.name} (HTTP ${sessionResp.status}), skipping ${filename}`);
+            return false;
+        }
+        if (!sessionJson.uuid) {
+            console.log(`No session UUID for ${this.name} (HTTP ${sessionResp.status}), skipping ${filename}`);
+            return false;
+        }
+        const downloadUrl = this.id
+            ? `https://api.itch.io/uploads/${d.id}/download?api_key=${token}&download_key_id=${this.id}&uuid=${sessionJson.uuid}`
+            : `https://api.itch.io/uploads/${d.id}/download?api_key=${token}&uuid=${sessionJson.uuid}`;
+        try {
+            await download(downloadUrl, this.dir, this.name, filename);
+        }
+        catch (e) {
+            if (e instanceof NoDownloadError) {
+                console.log(`HTTP response is not a download, skipping`);
+                await this._logError(outFile, filename, downloadUrl, 'Missing content-disposition header — skipped, please download manually');
+                return false;
+            }
+            if (e instanceof Error) {
+                console.log(`Download failed: ${this.name} - ${filename}`);
+                const code = e.code ?? 'unknown';
+                await this._logError(outFile, filename, downloadUrl, `Code: ${code}, reason: ${e.message} — skipped, please download manually`);
+                return false;
+            }
+            throw e;
+        }
+        if (md5Hash) {
+            const computed = await md5sum(outFile);
+            await writeFile(withSuffix(outFile, '.md5'), computed);
+            if (computed !== md5Hash) {
+                console.log(`Failed to verify ${filename}`);
+            }
+        }
+        return true;
+    }
+    async _logError(outFile, filename, requestUrl, detail) {
+        const safeUrl = requestUrl.replace(/api_key=[^&]+/, 'api_key=REDACTED');
+        await appendFile(path.join(this.outputDir, 'errors.txt'), [
+            ` Cannot download game/asset: ${this.gameSlug}`,
+            ` Publisher Name: ${this.publisherSlug}`,
+            ` Path: ${outFile}`,
+            ` File: ${filename}`,
+            ` Request URL: ${safeUrl}`,
+            ` ${detail}`,
+            ` ---------------------------------------------------------\n`,
+        ].join('\n'));
+    }
+}
+function withSuffix(filePath, newExt) {
+    const ext = path.extname(filePath);
+    return ext ? filePath.slice(0, -ext.length) + newExt : filePath + newExt;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export { NoDownloadError, download, fetchWithRetry, cleanPath, md5sum, runConcurrently, } from './utils.js';
+export { Game } from './game.js';
+export type { GameData, OwnedKeyData, Upload } from './game.js';
+export { Library } from './library.js';
+export type { UserProfile, Collection, BundleKey } from './library.js';
+export { loginAPI } from './login.js';

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { NoDownloadError, download, fetchWithRetry, cleanPath, md5sum, runConcurrently, } from './utils.js';
+export { Game } from './game.js';
+export { Library } from './library.js';
+export { loginAPI } from './login.js';

package/dist/src/library.d.ts

@@ -0,0 +1,46 @@
+import { Game } from './game.js';
+export interface UserProfile {
+    id: number;
+    username: string;
+    display_name?: string;
+    url?: string;
+    [key: string]: unknown;
+}
+export interface Collection {
+    id: number;
+    title: string;
+    games_count?: number;
+    [key: string]: unknown;
+}
+export interface BundleKey {
+    id: number;
+    bundle_id: number;
+    purchase_id?: number;
+    created_at?: string;
+    bundle: {
+        id: number;
+        title: string;
+        url?: string;
+        games_count?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export declare class Library {
+    token: string;
+    games: Game[];
+    jobs: number;
+    humanFolders: boolean;
+    outputDir: string;
+    dryRun: boolean;
+    filters: string[];
+    constructor(token: string, jobs?: number, humanFolders?: boolean, outputDir?: string, dryRun?: boolean, filters?: string[]);
+    loadGamePage(page: number): Promise<number>;
+    loadOwnedGames(): Promise<void>;
+    getProfile(): Promise<UserProfile | null>;
+    loadCollections(): Promise<Collection[]>;
+    loadCollection(id: number): Promise<void>;
+    loadBundles(): Promise<BundleKey[]>;
+    loadBundle(id: number): Promise<void>;
+    downloadLibrary(platform?: string): Promise<void>;
+}

package/dist/src/library.js

@@ -0,0 +1,155 @@
+import { Game } from './game.js';
+import { NoDownloadError, fetchWithRetry, runConcurrently } from './utils.js';
+const MAX_JOBS = 8;
+export class Library {
+    token;
+    games;
+    jobs;
+    humanFolders;
+    outputDir;
+    dryRun;
+    filters;
+    constructor(token, jobs = 4, humanFolders = false, outputDir = 'downloads', dryRun = false, filters = []) {
+        this.token = token;
+        this.games = [];
+        this.jobs = Math.min(jobs, MAX_JOBS);
+        this.humanFolders = humanFolders;
+        this.outputDir = outputDir;
+        this.dryRun = dryRun;
+        this.filters = filters.map((f) => f.toLowerCase());
+    }
+    async loadGamePage(page) {
+        console.log(`Loading page ${page}`);
+        const r = await fetchWithRetry(`https://api.itch.io/profile/owned-keys?page=${page}`, {
+            headers: { Authorization: this.token },
+        });
+        let j;
+        try {
+            j = (await r.json());
+        }
+        catch {
+            console.log(`Failed to load page ${page} (HTTP ${r.status}), stopping pagination`);
+            return 0;
+        }
+        if (!Array.isArray(j.owned_keys) || j.owned_keys.length === 0)
+            return 0;
+        for (const s of j.owned_keys) {
+            this.games.push(new Game(s, this.humanFolders, this.outputDir, this.dryRun));
+        }
+        return j.owned_keys.length;
+    }
+    async loadOwnedGames() {
+        let page = 1;
+        while (true) {
+            const n = await this.loadGamePage(page);
+            if (n === 0)
+                break;
+            page++;
+        }
+    }
+    async getProfile() {
+        const r = await fetchWithRetry('https://api.itch.io/profile', {
+            headers: { Authorization: this.token },
+        });
+        try {
+            const j = (await r.json());
+            return j.user ?? null;
+        }
+        catch {
+            console.log(`Failed to load profile (HTTP ${r.status})`);
+            return null;
+        }
+    }
+    async loadCollections() {
+        const r = await fetchWithRetry('https://api.itch.io/profile/collections', {
+            headers: { Authorization: this.token },
+        });
+        try {
+            const j = (await r.json());
+            return Array.isArray(j.collections) ? j.collections : [];
+        }
+        catch {
+            console.log(`Failed to load collections (HTTP ${r.status})`);
+            return [];
+        }
+    }
+    async loadCollection(id) {
+        let page = 1;
+        while (true) {
+            const r = await fetchWithRetry(`https://api.itch.io/collections/${id}/collection-games?page=${page}`, { headers: { Authorization: this.token } });
+            let j;
+            try {
+                j = (await r.json());
+            }
+            catch {
+                console.log(`Failed to load collection ${id} page ${page} (HTTP ${r.status}), stopping`);
+                break;
+            }
+            if (!Array.isArray(j.collection_games) || j.collection_games.length === 0)
+                break;
+            for (const item of j.collection_games) {
+                this.games.push(new Game({ game: item.game }, this.humanFolders, this.outputDir, this.dryRun));
+            }
+            page++;
+        }
+    }
+    async loadBundles() {
+        const r = await fetchWithRetry('https://api.itch.io/profile/owned-bundles', {
+            headers: { Authorization: this.token },
+        });
+        try {
+            const j = (await r.json());
+            return Array.isArray(j.bundle_keys) ? j.bundle_keys : [];
+        }
+        catch {
+            console.log(`Failed to load bundles (HTTP ${r.status})`);
+            return [];
+        }
+    }
+    async loadBundle(id) {
+        let page = 1;
+        while (true) {
+            const r = await fetchWithRetry(`https://api.itch.io/bundles/${id}/bundle-games?page=${page}`, { headers: { Authorization: this.token } });
+            let j;
+            try {
+                j = (await r.json());
+            }
+            catch {
+                console.log(`Failed to load bundle ${id} page ${page} (HTTP ${r.status}), stopping`);
+                break;
+            }
+            if (!Array.isArray(j.bundle_games) || j.bundle_games.length === 0)
+                break;
+            for (const item of j.bundle_games) {
+                this.games.push(new Game({ game: item.game }, this.humanFolders, this.outputDir, this.dryRun));
+            }
+            page++;
+        }
+    }
+    async downloadLibrary(platform) {
+        const games = this.filters.length
+            ? this.games.filter((g) => this.filters.some((f) => g.name.toLowerCase().includes(f)))
+            : this.games;
+        const total = games.length;
+        let downloaded = 0;
+        let errors = 0;
+        const tasks = games.map((g) => async () => {
+            try {
+                await g.download(this.token, platform);
+                downloaded++;
+                console.log(`Downloaded ${g.name} (${downloaded} of ${total})`);
+            }
+            catch (e) {
+                if (e instanceof NoDownloadError) {
+                    console.log(String(e));
+                    errors++;
+                }
+                else {
+                    throw e;
+                }
+            }
+        });
+        await runConcurrently(tasks, this.jobs);
+        console.log(`Downloaded ${downloaded} games, ${errors} errors`);
+    }
+}

package/dist/src/login.d.ts

@@ -0,0 +1,6 @@
+export interface WebSession {
+    get(url: string): Promise<Response>;
+    post(url: string, data: Record<string, string>): Promise<Response>;
+}
+export declare function loginAPI(user: string, password: string): Promise<string>;
+export declare function loginWeb(user: string, password: string): Promise<WebSession>;

package/dist/src/login.js

@@ -0,0 +1,87 @@
+const WARNING = 'Will print the response text (Please be careful as ' +
+    'this may contain personal data or allow others to login to your account):';
+export async function loginAPI(user, password) {
+    const body = new URLSearchParams({ username: user, password, source: 'desktop' });
+    const r = await fetch('https://api.itch.io/login', {
+        method: 'POST',
+        body,
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    });
+    if (r.status !== 200) {
+        console.log(`Error: ${r.status} is not 200`);
+        console.log(WARNING);
+        console.log(await r.text());
+        throw new Error('LoginAPI failed');
+    }
+    const t = (await r.json());
+    if (!t.success || !t.key?.key) {
+        console.log('Error: authentication failed');
+        console.log(WARNING);
+        throw new Error('LoginAPI: authentication failed');
+    }
+    return t.key.key;
+}
+export async function loginWeb(user, password) {
+    const cookies = new Map();
+    function buildCookieHeader() {
+        return [...cookies.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
+    }
+    function storeCookies(response) {
+        const setCookie = response.headers.get('set-cookie');
+        if (!setCookie)
+            return;
+        for (const part of setCookie.split(',')) {
+            const nameVal = part.trim().split(';')[0];
+            const eq = nameVal.indexOf('=');
+            if (eq !== -1) {
+                cookies.set(nameVal.slice(0, eq).trim(), nameVal.slice(eq + 1).trim());
+            }
+        }
+    }
+    // GET login page to obtain CSRF token
+    const loginPage = await fetch('https://itch.io/login', {
+        headers: { Cookie: buildCookieHeader() },
+        redirect: 'follow',
+    });
+    storeCookies(loginPage);
+    const html = await loginPage.text();
+    const csrfMatch = html.match(/name="csrf_token"\s+value="([^"]+)"/);
+    if (!csrfMatch)
+        throw new Error('Could not find CSRF token on login page');
+    const csrfToken = csrfMatch[1];
+    // POST credentials
+    const body = new URLSearchParams({ username: user, password, csrf_token: csrfToken });
+    const postResp = await fetch('https://itch.io/login', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/x-www-form-urlencoded',
+            Cookie: buildCookieHeader(),
+        },
+        body,
+        redirect: 'follow',
+    });
+    storeCookies(postResp);
+    if (postResp.status !== 200)
+        throw new Error('LoginWeb: POST failed');
+    const session = {
+        async get(url) {
+            const r = await fetch(url, { headers: { Cookie: buildCookieHeader() } });
+            storeCookies(r);
+            return r;
+        },
+        async post(url, data) {
+            const formBody = new URLSearchParams(data);
+            const r = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Cookie: buildCookieHeader(),
+                },
+                body: formBody,
+            });
+            storeCookies(r);
+            return r;
+        },
+    };
+    return session;
+}

package/dist/src/utils.d.ts

@@ -0,0 +1,8 @@
+export declare class NoDownloadError extends Error {
+    constructor(message: string);
+}
+export declare function fetchWithRetry(url: string, options?: RequestInit, retries?: number): Promise<Response>;
+export declare function download(url: string, dir: string, name: string, filename: string): Promise<void>;
+export declare function cleanPath(p: string): string;
+export declare function md5sum(filePath: string): Promise<string>;
+export declare function runConcurrently(tasks: Array<() => Promise<void>>, limit: number): Promise<void>;

package/dist/src/utils.js

@@ -0,0 +1,68 @@
+import { createHash } from 'crypto';
+import { createReadStream, createWriteStream } from 'fs';
+import path from 'path';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
+export class NoDownloadError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NoDownloadError';
+    }
+}
+export async function fetchWithRetry(url, options, retries = 3) {
+    let delay = 1000;
+    for (let attempt = 0;; attempt++) {
+        const r = await fetch(url, options);
+        if (r.status !== 429 || attempt >= retries)
+            return r;
+        const retryAfter = r.headers.get('retry-after');
+        const wait = retryAfter ? parseInt(retryAfter, 10) * 1000 : delay;
+        console.log(`Rate limited, retrying in ${wait / 1000}s...`);
+        await new Promise((res) => setTimeout(res, wait));
+        delay *= 2;
+    }
+}
+export async function download(url, dir, name, filename) {
+    console.log(`Downloading ${name} - ${filename}`);
+    const response = await fetch(url);
+    if (!response.headers.get('content-disposition')) {
+        throw new NoDownloadError('Http response is not a download, skipping');
+    }
+    const outPath = path.join(dir, filename);
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(outPath));
+    console.log(`Downloaded ${filename}`);
+}
+export function cleanPath(p) {
+    let clean = p.replace(/[<>:|?*"/\\]/g, '-');
+    clean = clean.replace(/(.)[.]\1+$/, '-');
+    return clean;
+}
+export async function md5sum(filePath) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash('md5');
+        const stream = createReadStream(filePath);
+        stream.on('data', (chunk) => hash.update(chunk));
+        stream.on('end', () => resolve(hash.digest('hex')));
+        stream.on('error', reject);
+    });
+}
+export async function runConcurrently(tasks, limit) {
+    const executing = new Set();
+    let firstError = null;
+    for (const task of tasks) {
+        const p = task()
+            .catch((e) => {
+            if (!firstError)
+                firstError = { value: e };
+        })
+            .finally(() => executing.delete(p));
+        executing.add(p);
+        if (executing.size >= limit) {
+            await Promise.race(executing);
+        }
+    }
+    // drain all in-flight tasks before propagating any error
+    await Promise.all(executing);
+    if (firstError)
+        throw firstError.value;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@irrg/itchio-hoard",
+  "version": "0.1.0",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "bin": {
+    "itchio-hoard": "dist/bin/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint src tests bin",
+    "fmt": "oxfmt src tests bin",
+    "fmt:check": "oxfmt --check src tests bin",
+    "itchio-hoard": "node --import tsx/esm bin/index.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "oxfmt": "^0.53.0",
+    "oxlint": "^1.68.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}