node-csfd-api 5.6.0-next.2 → 5.6.0-next.3

package/README.md

@@ -436,13 +436,14 @@ const excludeEpisodes = await csfd.userRatings('912-bart', {
 
 #### UserRatingsOptions
 
-| Option          | Type              | Default | Description                                                      |
-| --------------- | ----------------- | ------- | ---------------------------------------------------------------- |
-| `includesOnly`  | `CSFDFilmTypes[]` | `null`  | Include only specific content types (e.g., `['film', 'series']`) |
-| `exclude`       | `CSFDFilmTypes[]` | `null`  | Exclude specific content types (e.g., `['episode']`)             |
-| `allPages`      | `boolean`         | `false` | Fetch all pages of ratings                                       |
-| `allPagesDelay` | `number`          | `0`     | Delay between page requests in milliseconds                      |
-| `page`          | `number`          | `1`     | Fetch specific page number                                       |
+| Option          | Type                                    | Default     | Description                                                      |
+| --------------- | --------------------------------------- | ----------- | ---------------------------------------------------------------- |
+| `includesOnly`  | `CSFDFilmTypes[]`                       | `null`      | Include only specific content types (e.g., `['film', 'series']`) |
+| `exclude`       | `CSFDFilmTypes[]`                       | `null`      | Exclude specific content types (e.g., `['episode']`)             |
+| `allPages`      | `boolean`                               | `false`     | Fetch all pages of ratings                                       |
+| `allPagesDelay` | `number`                                | `0`         | Delay between page requests in milliseconds                      |
+| `page`          | `number`                                | `1`         | Fetch specific page number                                       |
+| `onProgress`    | `(page: number, total: number) => void` | `undefined` | Called on each page fetch — use for progress bars or logging     |
 
 > 📝 **Note**: `includesOnly` and `exclude` are mutually exclusive. If both are provided, `includesOnly` takes precedence.
 >
@@ -524,58 +525,89 @@ Same options as [UserRatingsOptions](#userrationsoptions).
 
 ## 💻 CLI Tools
 
-This library comes with a powerful CLI that exposes several tools. You can run the CLI either via `npx` (without installation) or by installing it globally via Homebrew (macOS/Linux).
+This library ships with a CLI exposing several tools. Choose the installation method that fits your workflow.
 
-### Installation / Usage
+### Installation
 
-**Option A: NPX (No installation required)**
+**Option A: npx** _(no installation required)_
+
+> Runs directly via Node.js
 
 ```bash
 npx node-csfd-api <command>
 ```
 
-**Option B: Homebrew for macOS/Linux (Global installation)**
+**Option B: Homebrew** _(macOS)_
 
 ```bash
 brew install bartholomej/tap/csfd
+```
+
+**Option C: Install script** _(macOS & Linux)_
+
+> Installs the latest stable release as a standalone binary to `~/.local/bin/csfd`.
 
-csfd <command>
+```bash
+curl -fsSL https://raw.githubusercontent.com/bartholomej/node-csfd-api/master/install.sh | bash
+## Install specific version
+# curl -fsSL https://raw.githubusercontent.com/bartholomej/node-csfd-api/master/install.sh | CSFD_VERSION=5.5.0 bash
 ```
 
-> 💡 _Note: The examples below use `npx node-csfd-api`, but if you installed via Homebrew, simply replace it with `csfd` (e.g., `csfd export ratings 912`)._
+**Option D: Windows** _(manual download)_
+
+Download `csfd-windows-x64.zip` from the [latest release](https://github.com/bartholomej/node-csfd-api/releases/latest), extract `csfd.exe`, and add it to your `PATH`.
+
+> ⚠️ Windows may show a SmartScreen warning ("Windows protected your PC") because the binary is not code-signed. To proceed: click **More info** → **Run anyway**. Alternatively, right-click the `.exe` → Properties → check **Unblock**.
 
 ---
 
-### 1. Export Ratings (CSV, JSON & Letterboxd)
+### CLI Examples
+
+> 💡 The examples below use `csfd` (Options B, C & D). If you use npx, replace it with `npx node-csfd-api` — e.g. `npx node-csfd-api export ratings 912`.
 
-> Backup your personal user ratings to CSV (default), JSON, or Letterboxd format. Use this tool just to keep a local copy of your data.
+#### 1. Movie Details
 
 ```bash
-# Export to CSV (default) -> saves as <userId>-ratings.csv
-npx node-csfd-api export ratings 912
+csfd movie 535121
+# npx node-csfd-api movie 535121
+csfd movie 535121 --json   # raw JSON output, pipe-friendly
+# npx node-csfd-api movie 535121 --json
+```
 
-# Export to JSON -> saves as <userId>-ratings.json
-npx node-csfd-api export ratings 912 --json
+#### 2. Export Ratings (CSV, JSON & Letterboxd)
 
-# Export to Letterboxd CSV -> saves as <userId>-for-letterboxd.csv
-npx node-csfd-api export ratings 912 --letterboxd
-```
+> Backup your personal user ratings. _Use this tool just to keep a local copy of your data._
 
-### 2. REST API Server
+```bash
+csfd export ratings 912            # CSV (default) -> <userId>-ratings.csv
+# npx node-csfd-api export ratings 912
+csfd export ratings 912 --json     # JSON -> <userId>-ratings.json
+# npx node-csfd-api export ratings 912 --json
+csfd export ratings 912 --letterboxd  # Letterboxd CSV -> <userId>-for-letterboxd.csv
+# npx node-csfd-api export ratings 912 --letterboxd
+```
 
-Run a standalone REST API server.
+#### 3. Export Reviews (CSV & JSON)
 
 ```bash
-npx node-csfd-api server
-# Server listening on port 3000
+csfd export reviews 912            # CSV (default) -> <userId>-reviews.csv
+# npx node-csfd-api export reviews 912
+csfd export reviews 912 --json     # JSON -> <userId>-reviews.json
+# npx node-csfd-api export reviews 912 --json
 ```
 
-### 3. MCP Server for AI Agents
+#### 4. REST API Server
+
+```bash
+csfd server
+# npx node-csfd-api server
+```
 
-Run the Model Context Protocol server for AI agents.
+#### 5. MCP Server for AI Agents
 
 ```bash
-npx node-csfd-api mcp
+csfd mcp
+# npx node-csfd-api mcp
 ```
 
 ## 🤖 MCP Server (Model Context Protocol)

package/bin/export-ratings.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { csfd } from "../index.js";
+import { escapeCsvField, renderProgress } from "./utils.js";
 import { writeFile } from "node:fs/promises";
 
 //#region src/bin/export-ratings.ts
@@ -12,15 +13,13 @@ async function runRatingsExport(userId, options) {
 	try {
 		if (options.format === "letterboxd") csfd.setOptions({ language: "en" });
 		console.log(`Fetching ratings for user ${userId} (${options.format.toUpperCase()})...`);
-		const ratings = await csfd.userRatings(userId, options.userRatingsOptions);
+		const ratings = await csfd.userRatings(userId, {
+			...options.userRatingsOptions,
+			onProgress: renderProgress
+		});
 		console.log(`Fetched ${ratings.length} ratings.`);
 		let content = "";
 		let fileName = "";
-		const escapeCsvField = (value) => {
-			const needsQuotes = /[",\n\r]/.test(value);
-			const escaped = value.replaceAll("\"", "\"\"");
-			return needsQuotes ? `"${escaped}"` : escaped;
-		};
 		if (options.format === "letterboxd") {
 			content = ["Title,Year,Rating,WatchedDate", ...ratings.map((r) => {
 				return `${escapeCsvField(r.title ?? "")},${r.year ?? ""},${r.userRating ?? ""},${escapeCsvField(r.userDate ?? "")}`;

package/bin/export-reviews.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { csfd } from "../index.js";
+import { escapeCsvField, renderProgress } from "./utils.js";
+import { writeFile } from "node:fs/promises";
+
+//#region src/bin/export-reviews.ts
+async function runReviewsExport(userId, options) {
+	try {
+		console.log(`Fetching reviews for user ${userId} (${options.format.toUpperCase()})...`);
+		const reviews = await csfd.userReviews(userId, {
+			...options.userReviewsOptions,
+			onProgress: renderProgress
+		});
+		console.log(`Fetched ${reviews.length} reviews.`);
+		let content = "";
+		let fileName = "";
+		if (options.format === "json") {
+			content = JSON.stringify(reviews, null, 2);
+			fileName = `${userId}-reviews.json`;
+		} else {
+			content = [[
+				"id",
+				"title",
+				"year",
+				"type",
+				"colorRating",
+				"userRating",
+				"date",
+				"url",
+				"text"
+			].join(","), ...reviews.map((r) => [
+				r.id,
+				escapeCsvField(r.title ?? ""),
+				r.year ?? "",
+				escapeCsvField(r.type ?? ""),
+				escapeCsvField(r.colorRating ?? ""),
+				r.userRating ?? "",
+				escapeCsvField(r.userDate ?? ""),
+				escapeCsvField(r.url ?? ""),
+				escapeCsvField(r.text ?? "")
+			].join(","))].join("\n");
+			fileName = `${userId}-reviews.csv`;
+		}
+		await writeFile(fileName, content);
+		console.log("Saved in file:", `./${fileName}`);
+	} catch (error) {
+		console.error("Error exporting reviews:", error);
+		throw error;
+	}
+}
+
+//#endregion
+export { runReviewsExport };

package/bin/lookup-movie.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { csfd } from "../index.js";
+import { c } from "./utils.js";
+
+//#region src/bin/lookup-movie.ts
+async function runMovieLookup(movieId, json) {
+	const movie = await csfd.movie(movieId);
+	if (json) console.log(JSON.stringify(movie, null, 2));
+	else printMovie(movie);
+}
+function printMovie(movie) {
+	const ratingColor = movie.colorRating === "good" ? c.green : movie.colorRating === "average" ? c.yellow : movie.colorRating === "bad" ? c.red : c.dim;
+	const row = (label, value) => value ? `  ${c.dim(label.padEnd(11))} ${value}` : "";
+	const names = (arr, max = 5) => arr.slice(0, max).map((x) => x.name).join(", ");
+	const description = movie.descriptions?.[0] ? movie.descriptions[0].length > 160 ? movie.descriptions[0].slice(0, 157) + "..." : movie.descriptions[0] : "";
+	const vod = movie.vod?.map((v) => v.title).join(", ") ?? "";
+	const lines = [
+		"",
+		c.bold(movie.title) + c.dim(` (${movie.year ?? "?"})`) + "  ·  " + c.dim(movie.type ?? ""),
+		c.dim("─".repeat(52)),
+		row("Rating", movie.rating != null ? ratingColor(c.bold(movie.rating + "%")) + c.dim(`  (${movie.ratingCount?.toLocaleString()} ratings)`) : c.dim("no rating")),
+		row("Genres", movie.genres?.join(", ") ?? ""),
+		row("Origins", movie.origins?.join(", ") ?? ""),
+		row("Duration", movie.duration ? movie.duration + " min" : ""),
+		row("Directors", names(movie.creators?.directors ?? [])),
+		row("Cast", names(movie.creators?.actors ?? [])),
+		description ? "\n  " + c.dim(description) : "",
+		vod ? "\n" + row("VOD", vod) : "",
+		row("URL", c.dim(movie.url ?? "")),
+		""
+	].filter(Boolean);
+	console.log(lines.join("\n"));
+}
+
+//#endregion
+export { runMovieLookup };

package/bin/utils.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+//#region src/bin/utils.ts
+const useColor = process.stdout.isTTY && !process.env["NO_COLOR"];
+const c = {
+	bold: (s) => useColor ? `\x1b[1m${s}\x1b[22m` : s,
+	dim: (s) => useColor ? `\x1b[2m${s}\x1b[22m` : s,
+	cyan: (s) => useColor ? `\x1b[36m${s}\x1b[39m` : s,
+	green: (s) => useColor ? `\x1b[32m${s}\x1b[39m` : s,
+	yellow: (s) => useColor ? `\x1b[33m${s}\x1b[39m` : s,
+	red: (s) => useColor ? `\x1b[31m${s}\x1b[39m` : s
+};
+const err = (msg) => c.red(c.bold("✖ Error:")) + " " + msg;
+const escapeCsvField = (value) => {
+	const needsQuotes = /[",\n\r]/.test(value);
+	const escaped = value.replaceAll("\"", "\"\"");
+	return needsQuotes ? `"${escaped}"` : escaped;
+};
+const renderProgress = (page, total) => {
+	const pct = Math.round(page / total * 100);
+	const filled = Math.round(page / total * 20);
+	const bar = "█".repeat(filled) + "░".repeat(20 - filled);
+	process.stdout.write(`\r  [${bar}]  ${page}/${total} pages  ${pct}%`);
+	if (page === total) process.stdout.write("\n");
+};
+
+//#endregion
+export { c, err, escapeCsvField, renderProgress };

package/cli.js

@@ -1,5 +1,14 @@
 #!/usr/bin/env node
+import { c, err } from "./bin/utils.js";
+
 //#region src/cli.ts
+/**
+* Main CLI entry point for node-csfd-api.
+*/
+const GITHUB_REPO = "bartholomej/node-csfd-api";
+const GITHUB_API_LATEST = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+const GITHUB_RELEASES_URL = `https://github.com/${GITHUB_REPO}/releases/latest`;
+const INSTALL_SH_URL = `https://raw.githubusercontent.com/${GITHUB_REPO}/master/install.sh`;
 function getCommandName() {
 	const scriptPath = process.argv[1] ?? "";
 	const basename = scriptPath.split("/").pop() ?? "";
@@ -7,9 +16,23 @@ function getCommandName() {
 	if (scriptPath.includes("node-csfd-api")) return "npx node-csfd-api";
 	return "csfd";
 }
+function parseNumericArg(raw, usage) {
+	const n = Number(raw);
+	if (!raw || isNaN(n)) {
+		console.error(err("Please provide a valid numeric ID."));
+		console.log(c.dim(`  Usage: ${usage}`));
+		process.exit(1);
+	}
+	return n;
+}
+function parseFormat(args) {
+	return args.includes("--json") ? "json" : "csv";
+}
 async function main() {
 	const args = process.argv.slice(2);
-	switch (args[0]) {
+	const command = args[0];
+	const updateHint = new Set(["update"]).has(command) ? null : checkForUpdateInBackground();
+	switch (command) {
 		case "server":
 		case "api":
 			try {
@@ -29,20 +52,9 @@ async function main() {
 			break;
 		case "export":
 			if (args[1] === "ratings") {
-				const userIdRaw = args[2];
-				const userId = Number(userIdRaw);
-				if (!userIdRaw || isNaN(userId)) {
-					console.error("Error: Please provide a valid numeric User ID.");
-					console.log(`Usage: ${getCommandName()} export ratings <userId> [options]`);
-					process.exit(1);
-				}
+				const userId = parseNumericArg(args[2], `${getCommandName()} export ratings <userId> [options]`);
 				const isLetterboxd = args.includes("--letterboxd");
-				const isJson = args.includes("--json");
-				const isCsv = args.includes("--csv");
-				let format = "csv";
-				if (isLetterboxd) format = "letterboxd";
-				else if (isJson) format = "json";
-				else if (isCsv) format = "csv";
+				const format = isLetterboxd ? "letterboxd" : parseFormat(args);
 				try {
 					const { runRatingsExport } = await import("./bin/export-ratings.js");
 					await runRatingsExport(userId, {
@@ -54,50 +66,208 @@ async function main() {
 						}
 					});
 				} catch (error) {
-					console.error("Failed to run export:", error);
+					console.error(err("Failed to run export:"), error);
+					process.exit(1);
+				}
+			} else if (args[1] === "reviews") {
+				const userId = parseNumericArg(args[2], `${getCommandName()} export reviews <userId> [options]`);
+				try {
+					const { runReviewsExport } = await import("./bin/export-reviews.js");
+					await runReviewsExport(userId, {
+						format: parseFormat(args),
+						userReviewsOptions: {
+							allPages: true,
+							allPagesDelay: 1e3
+						}
+					});
+				} catch (error) {
+					console.error(err("Failed to run export:"), error);
 					process.exit(1);
 				}
 			} else if (args[1] === "letterboxd") {
-				console.warn("Deprecation Warning: \"export letterboxd\" is deprecated. Please use \"export ratings <id> --letterboxd\" instead.");
-				console.log(`Usage: ${getCommandName()} export ratings <userId> --letterboxd`);
+				console.warn(c.yellow(c.bold("⚠ Deprecated:")) + " \"export letterboxd\" is removed. Use \"export ratings <id> --letterboxd\" instead.");
+				console.log(c.dim(`  Usage: ${getCommandName()} export ratings <userId> --letterboxd`));
 				process.exit(1);
 			} else {
-				console.error(`Unknown export target: ${args[1]}`);
+				console.error(err(`Unknown export target: ${c.bold(String(args[1]))}`));
 				printUsage();
 				process.exit(1);
 			}
 			break;
+		case "movie": {
+			const movieId = parseNumericArg(args[1], `${getCommandName()} movie <id> [--json]`);
+			try {
+				const { runMovieLookup } = await import("./bin/lookup-movie.js");
+				await runMovieLookup(movieId, args.includes("--json"));
+			} catch (error) {
+				console.error(err("Failed to fetch movie:"), error);
+				process.exit(1);
+			}
+			break;
+		}
 		case "--version":
 		case "-v":
-			console.log("5.6.0-next.2");
+			console.log(c.bold("5.6.0-next.3"));
+			break;
+		case "update":
+			await runUpdate();
 			break;
 		default:
 			printUsage();
 			break;
 	}
+	if (updateHint) await updateHint;
+}
+function isRunningViaNpx() {
+	const base = (process.execPath ?? "").split("/").pop() ?? "";
+	return base === "node" || base === "node.exe" || base === "bun";
+}
+function isRunningViaHomebrew() {
+	const exec = process.execPath ?? "";
+	return exec.includes("/homebrew/") || exec.includes("/Cellar/");
+}
+function compareSemver(a, b) {
+	const parse = (v) => {
+		const [main, pre = ""] = v.split("-");
+		const [major, minor, patch] = main.split(".").map(Number);
+		return {
+			major,
+			minor,
+			patch,
+			pre
+		};
+	};
+	const va = parse(a);
+	const vb = parse(b);
+	if (va.major !== vb.major) return va.major - vb.major;
+	if (va.minor !== vb.minor) return va.minor - vb.minor;
+	if (va.patch !== vb.patch) return va.patch - vb.patch;
+	if (va.pre && !vb.pre) return -1;
+	if (!va.pre && vb.pre) return 1;
+	return va.pre.localeCompare(vb.pre);
+}
+async function fetchLatestVersion(timeoutMs = 5e3) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		return (await (await fetch(GITHUB_API_LATEST, { signal: controller.signal })).json()).tag_name?.replace(/^v/, "") ?? "";
+	} finally {
+		clearTimeout(timer);
+	}
+}
+function printUpgradeInstructions(latest) {
+	console.log(c.green(c.bold("↑ New version available: ")) + c.bold(latest));
+	if (isRunningViaNpx()) {
+		console.log("\n" + c.bold("Run:"));
+		console.log("  " + c.cyan("npx node-csfd-api@latest <command>"));
+	} else if (isRunningViaHomebrew()) {
+		console.log("\n" + c.bold("Run:"));
+		console.log("  " + c.cyan("brew upgrade csfd"));
+	} else if (process.platform === "win32") {
+		console.log("\n" + c.bold("Download the latest release from:"));
+		console.log("  " + c.cyan(GITHUB_RELEASES_URL));
+	} else {
+		console.log("\n" + c.bold("Run:"));
+		console.log("  " + c.cyan(`curl -fsSL ${INSTALL_SH_URL} | bash`));
+	}
+}
+const UPDATE_CACHE_TTL = 1440 * 60 * 1e3;
+function getUpdateCachePath() {
+	const home = process.env["HOME"] || process.env["USERPROFILE"] || "";
+	return `${process.platform === "win32" ? process.env["APPDATA"] || home : process.env["XDG_CONFIG_HOME"] || `${home}/.config`}/csfd/update-check.json`;
+}
+async function checkForUpdateInBackground() {
+	try {
+		const { readFileSync, writeFileSync, mkdirSync } = await import("node:fs");
+		const { dirname } = await import("node:path");
+		const cachePath = getUpdateCachePath();
+		let cache = null;
+		try {
+			cache = JSON.parse(readFileSync(cachePath, "utf-8"));
+		} catch {}
+		const now = Date.now();
+		let latestVersion = cache?.latestVersion ?? "";
+		if (!cache || now - cache.lastCheck > UPDATE_CACHE_TTL) try {
+			const fetched = await fetchLatestVersion(3e3);
+			if (fetched) {
+				latestVersion = fetched;
+				try {
+					mkdirSync(dirname(cachePath), { recursive: true });
+					writeFileSync(cachePath, JSON.stringify({
+						lastCheck: now,
+						latestVersion
+					}));
+				} catch {}
+			}
+		} catch {}
+		if (!latestVersion || compareSemver("5.6.0-next.3", latestVersion) >= 0) return;
+		console.log("");
+		console.log(c.dim("  " + "─".repeat(44)));
+		console.log(`  ${c.yellow(c.bold("↑ Update available:"))} ${c.dim("5.6.0-next.3")} → ${c.bold(c.green(latestVersion))}`);
+		console.log(`  ${c.dim("Run")} ${c.cyan(getCommandName() + " update")} ${c.dim("for upgrade instructions.")}`);
+	} catch {}
+}
+async function runUpdate() {
+	console.log(c.dim("Current version: ") + c.bold("5.6.0-next.3"));
+	console.log(c.dim("Checking for updates..."));
+	let latest;
+	try {
+		latest = await fetchLatestVersion();
+	} catch {
+		console.error(err("Could not reach GitHub API."));
+		process.exit(1);
+	}
+	if (!latest) {
+		console.error(err("Could not determine latest version."));
+		process.exit(1);
+	}
+	const cmp = compareSemver("5.6.0-next.3", latest);
+	if (cmp === 0) {
+		console.log(c.green("✔ Already up to date."));
+		return;
+	}
+	if (cmp > 0) {
+		console.log(c.yellow("⚠ You are running a pre-release version.") + c.dim(` Latest stable: ${latest}`));
+		return;
+	}
+	printUpgradeInstructions(latest);
 }
 function printUsage() {
 	const cmd = getCommandName();
+	const header = c.bold(c.cyan("csfd")) + " " + c.dim(`v5.6.0-next.3`);
+	const usage = c.bold("Usage:") + `  ${c.cyan(cmd)} ${c.dim("<command> [options]")}`;
+	const section = (title) => c.bold(title);
+	const cmd_ = (name) => "  " + c.cyan(name);
+	const flag_ = (name) => "  " + c.dim(name);
+	const desc = (text) => c.dim(text);
+	const sub_ = (name) => "    " + c.dim(name);
 	console.log(`
-Usage: ${cmd} <command> [options]
+${header}
+
+${usage}
 
-Commands:
-  server, api                Start the REST API server
-  mcp                        Start the MCP (Model Context Protocol) server for AI agents
-  export ratings <userId>    Export user ratings to CSV (default), JSON, or Letterboxd format
-    Options:
-      --csv                  Export to CSV format (default)
-      --json                 Export to JSON format
-      --letterboxd           Export to Letterboxd-compatible CSV format
-  help                       Show this help message
+${section("Commands:")}
+${cmd_("server, api")}               ${desc("Start the REST API server")}
+${cmd_("mcp")}                       ${desc("Start the MCP server for AI agents")}
+${cmd_("export ratings <userId>")}   ${desc("Export user ratings")}
+${sub_("--csv")}                     ${desc("CSV format (default)")}
+${sub_("--json")}                    ${desc("JSON format")}
+${sub_("--letterboxd")}              ${desc("Letterboxd-compatible CSV")}
+${cmd_("export reviews <userId>")}   ${desc("Export user reviews")}
+${sub_("--csv")}                     ${desc("CSV format (default)")}
+${sub_("--json")}                    ${desc("JSON format")}
+${cmd_("movie <id>")}                ${desc("Show movie details")}
+${sub_("--json")}                    ${desc("Output raw JSON")}
+${cmd_("update")}                    ${desc("Check for updates")}
+${cmd_("help")}                      ${desc("Show this help")}
 
-Flags:
-  --version, -v              Show version
-  --help, -h                 Show this help message
+${section("Flags:")}
+${flag_("-v, --version")}            ${desc("Show version")}
+${flag_("-h, --help")}               ${desc("Show this help")}
 `);
 }
 main().catch((error) => {
-	console.error("Fatal error:", error);
+	console.error(err("Fatal: " + String(error)));
 	process.exit(1);
 });
 

package/dto/user-ratings.d.cts

@@ -20,6 +20,13 @@ interface CSFDUserRatingConfig {
    * Specific page number to fetch (e.g., 2 for second page)
    */
   page?: number;
+  /**
+   * Called on each page fetch when `allPages` is enabled.
+   * Useful for rendering progress in CLI tools or custom logging.
+   * @param page - Current page number
+   * @param total - Total number of pages
+   */
+  onProgress?: (page: number, total: number) => void;
 }
 type CSFDColors = 'lightgrey' | 'blue' | 'red' | 'grey';
 //#endregion

package/dto/user-ratings.d.ts

@@ -20,6 +20,13 @@ interface CSFDUserRatingConfig {
    * Specific page number to fetch (e.g., 2 for second page)
    */
   page?: number;
+  /**
+   * Called on each page fetch when `allPages` is enabled.
+   * Useful for rendering progress in CLI tools or custom logging.
+   * @param page - Current page number
+   * @param total - Total number of pages
+   */
+  onProgress?: (page: number, total: number) => void;
 }
 type CSFDColors = 'lightgrey' | 'blue' | 'red' | 'grey';
 //#endregion

package/dto/user-reviews.d.cts

@@ -22,6 +22,13 @@ interface CSFDUserReviewsConfig {
    * Specific page number to fetch (e.g., 2 for second page)
    */
   page?: number;
+  /**
+   * Called on each page fetch when `allPages` is enabled.
+   * Useful for rendering progress in CLI tools or custom logging.
+   * @param page - Current page number
+   * @param total - Total number of pages
+   */
+  onProgress?: (page: number, total: number) => void;
 }
 //#endregion
 export { CSFDUserReviews, CSFDUserReviewsConfig };

package/dto/user-reviews.d.ts

@@ -22,6 +22,13 @@ interface CSFDUserReviewsConfig {
    * Specific page number to fetch (e.g., 2 for second page)
    */
   page?: number;
+  /**
+   * Called on each page fetch when `allPages` is enabled.
+   * Useful for rendering progress in CLI tools or custom logging.
+   * @param page - Current page number
+   * @param total - Total number of pages
+   */
+  onProgress?: (page: number, total: number) => void;
 }
 //#endregion
 export { CSFDUserReviews, CSFDUserReviewsConfig };

package/fetchers/index.cjs

@@ -1,4 +1,5 @@
 const require_fetch_polyfill = require("./fetch.polyfill.cjs");
+const require_vars = require("../vars.cjs");
 //#region src/fetchers/index.ts
 const browserProfiles = [
 	{
@@ -61,11 +62,11 @@ const fetchPage = async (url, optionsRequest) => {
 		});
 		if (!response.ok) throw new Error(`node-csfd-api: Bad response ${response.status} for url: ${url}`);
 		const html = await response.text();
-		if (html.includes("Making sure you're not a bot!")) console.warn("node-csfd-api: Trap detected.");
+		if (html.includes("Making sure you're not a bot!")) console.warn("[node-csfd-api] Trap detected. You may be rate-limited or blocked by ČSFD.");
 		return html;
 	} catch (e) {
-		if (e instanceof Error) console.error(e.message);
-		else console.error(String(e));
+		if (e instanceof Error) console.error(require_vars.LIB_PREFIX, e.message);
+		else console.error(require_vars.LIB_PREFIX, String(e));
 		return "Error";
 	}
 };