@remote-app/qbittorrent-client 0.22.0

package/README.md

@@ -0,0 +1,121 @@
+# @remote-app/qbittorrent-client
+
+![npm](https://img.shields.io/npm/v/@remote-app/qbittorrent-client)
+
+A lightweight [qBittorrent](https://www.qbittorrent.org/) WebUI API client for Node.js and React Native.
+
+## Install
+
+```bash
+npm install @remote-app/qbittorrent-client
+```
+
+## Usage
+
+```typescript
+import QBittorrentClient from "@remote-app/qbittorrent-client";
+
+const client = new QBittorrentClient({
+  url: "http://localhost:8080",
+  username: "admin",
+  password: "adminadmin",
+});
+
+// List all torrents
+const torrents = await client.info();
+
+// List torrents with filters
+const downloading = await client.info({ filter: "downloading" });
+
+// Add a torrent by URL
+await client.add({ urls: "magnet:?xt=urn:btih:..." });
+
+// Start and stop torrents
+await client.start(["<hash>"]);
+await client.stop(["<hash>"]);
+
+// Get transfer info
+const transfer = await client.transferInfo();
+console.log(transfer.dl_info_speed, transfer.up_info_speed);
+```
+
+The client handles cookie-based authentication automatically and re-authenticates on 403 responses.
+
+## API
+
+### Torrents
+
+| Method | Description |
+|---|---|
+| `info(params?)` | List torrents (with optional filters, sorting, pagination) |
+| `properties(hash)` | Get torrent properties |
+| `files(hash)` | Get torrent files |
+| `trackers(hash)` | Get torrent trackers |
+| `pieceStates(hash)` | Get piece download states |
+| `add(params)` | Add torrent (by URL or `.torrent` Blob) |
+| `delete(hashes, deleteFiles?)` | Delete torrents |
+| `start(hashes)` | Start torrents |
+| `stop(hashes)` | Stop torrents |
+| `recheck(hashes)` | Recheck torrents |
+| `reannounce(hashes)` | Reannounce torrents |
+| `setDownloadLimit(hashes, limit)` | Set per-torrent download limit (bytes/s) |
+| `setUploadLimit(hashes, limit)` | Set per-torrent upload limit (bytes/s) |
+| `setShareLimits(hashes, ratio, seedingTime, inactiveTime)` | Set share limits |
+| `setLocation(hashes, location)` | Move torrents to a new location |
+| `rename(hash, name)` | Rename a torrent |
+| `filePrio(hash, fileIds, priority)` | Set file priority |
+| `setForceStart(hashes, value)` | Force start torrents |
+| `topPrio(hashes)` / `bottomPrio(hashes)` | Move to top/bottom of queue |
+| `increasePrio(hashes)` / `decreasePrio(hashes)` | Move up/down in queue |
+
+### Transfer
+
+| Method | Description |
+|---|---|
+| `transferInfo()` | Get global transfer info |
+| `speedLimitsMode()` | Get alternative speed limits mode (0 or 1) |
+| `toggleSpeedLimitsMode()` | Toggle alternative speed limits |
+| `setGlobalDownloadLimit(limit)` | Set global download limit (bytes/s) |
+| `setGlobalUploadLimit(limit)` | Set global upload limit (bytes/s) |
+
+### App
+
+| Method | Description |
+|---|---|
+| `version()` | Get qBittorrent version |
+| `webapiVersion()` | Get WebUI API version |
+| `preferences()` | Get application preferences |
+| `setPreferences(prefs)` | Set application preferences |
+| `defaultSavePath()` | Get default save path |
+| `shutdown()` | Shutdown qBittorrent |
+
+### Peers
+
+| Method | Description |
+|---|---|
+| `torrentPeers(hash, rid?)` | Get torrent peers data |
+
+## Error handling
+
+```typescript
+import QBittorrentClient, {
+  HTTPError,
+  QBittorrentError,
+} from "@remote-app/qbittorrent-client";
+
+try {
+  await client.info();
+} catch (error) {
+  if (error instanceof HTTPError) {
+    // Non-200 HTTP response (e.g. 403 Forbidden)
+    console.error(error.status, error.message);
+  } else if (error instanceof QBittorrentError) {
+    // API-level error (e.g. login failure, failed to add torrent)
+    console.error(error.message);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,275 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+
+//#region src/error.ts
+var HTTPError = class extends Error {
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+		this.name = "HTTPError";
+	}
+};
+var QBittorrentError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "QBittorrentError";
+	}
+};
+
+//#endregion
+//#region src/client.ts
+var QBittorrentClient = class {
+	constructor(config) {
+		this.config = config;
+		this.sid = null;
+		this.loggedIn = false;
+		this.loginPromise = null;
+	}
+	baseUrl() {
+		return this.config.url.replace(/\/+$/, "");
+	}
+	async login() {
+		if (this.loginPromise) return this.loginPromise;
+		this.loginPromise = this.doLogin();
+		try {
+			await this.loginPromise;
+		} finally {
+			this.loginPromise = null;
+		}
+	}
+	async doLogin() {
+		const baseUrl = this.baseUrl();
+		const body = new URLSearchParams();
+		if (this.config.username) body.set("username", this.config.username);
+		if (this.config.password) body.set("password", this.config.password);
+		const response = await fetch(`${baseUrl}/api/v2/auth/login`, {
+			method: "POST",
+			headers: {
+				Referer: baseUrl,
+				"Content-Type": "application/x-www-form-urlencoded"
+			},
+			credentials: "include",
+			body: body.toString()
+		});
+		if (!response.ok) throw new HTTPError(response.status, response.statusText);
+		if (await response.text() !== "Ok.") throw new QBittorrentError("Login failed: invalid credentials");
+		const cookie = response.headers.get("set-cookie");
+		if (cookie) {
+			const match = cookie.match(/SID=([^;]+)/);
+			if (match) this.sid = match[1];
+		}
+		this.loggedIn = true;
+	}
+	async get(path, params) {
+		return this.request("GET", path, params);
+	}
+	async post(path, body) {
+		return this.request("POST", path, void 0, body);
+	}
+	async request(method, path, params, body, retry = true) {
+		if (!this.loggedIn) await this.login();
+		const baseUrl = this.baseUrl();
+		let url = `${baseUrl}${path}`;
+		if (params) {
+			const qs = new URLSearchParams(params);
+			url += `?${qs.toString()}`;
+		}
+		const headers = { Referer: baseUrl };
+		if (this.sid) headers["Cookie"] = `SID=${this.sid}`;
+		let fetchBody;
+		if (body instanceof URLSearchParams) {
+			headers["Content-Type"] = "application/x-www-form-urlencoded";
+			fetchBody = body.toString();
+		} else fetchBody = body;
+		const response = await fetch(url, {
+			method,
+			headers,
+			body: fetchBody,
+			credentials: "include"
+		});
+		if (response.status === 403 && retry) {
+			this.sid = null;
+			this.loggedIn = false;
+			return this.request(method, path, params, body, false);
+		}
+		if (!response.ok) throw new HTTPError(response.status, response.statusText);
+		const text = await response.text();
+		if (!text) return void 0;
+		try {
+			return JSON.parse(text);
+		} catch {
+			return text;
+		}
+	}
+	hashes(hashes) {
+		return hashes.join("|");
+	}
+	async info(params) {
+		const qs = {};
+		if (params) {
+			for (const [key, value] of Object.entries(params)) if (value !== void 0) qs[key] = String(value);
+		}
+		return this.get("/api/v2/torrents/info", qs);
+	}
+	async properties(hash) {
+		return this.get("/api/v2/torrents/properties", { hash });
+	}
+	async files(hash) {
+		return this.get("/api/v2/torrents/files", { hash });
+	}
+	async trackers(hash) {
+		return this.get("/api/v2/torrents/trackers", { hash });
+	}
+	async pieceStates(hash) {
+		return this.get("/api/v2/torrents/pieceStates", { hash });
+	}
+	async add(params) {
+		const form = new FormData();
+		for (const [key, value] of Object.entries(params)) {
+			if (value === void 0) continue;
+			if (key === "torrents") form.append("torrents", value, "torrent");
+			else form.append(key, String(value));
+		}
+		if (await this.post("/api/v2/torrents/add", form) === "Fails.") throw new QBittorrentError("Failed to add torrent");
+	}
+	async delete(hashes, deleteFiles = false) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		body.set("deleteFiles", String(deleteFiles));
+		await this.post("/api/v2/torrents/delete", body);
+	}
+	async start(hashes) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		await this.post("/api/v2/torrents/start", body);
+	}
+	async stop(hashes) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		await this.post("/api/v2/torrents/stop", body);
+	}
+	async recheck(hashes) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		await this.post("/api/v2/torrents/recheck", body);
+	}
+	async reannounce(hashes) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		await this.post("/api/v2/torrents/reannounce", body);
+	}
+	async setDownloadLimit(hashes, limit) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		body.set("limit", String(limit));
+		await this.post("/api/v2/torrents/setDownloadLimit", body);
+	}
+	async setUploadLimit(hashes, limit) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		body.set("limit", String(limit));
+		await this.post("/api/v2/torrents/setUploadLimit", body);
+	}
+	async setShareLimits(hashes, ratioLimit, seedingTimeLimit, inactiveSeedingTimeLimit) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		body.set("ratioLimit", String(ratioLimit));
+		body.set("seedingTimeLimit", String(seedingTimeLimit));
+		body.set("inactiveSeedingTimeLimit", String(inactiveSeedingTimeLimit));
+		await this.post("/api/v2/torrents/setShareLimits", body);
+	}
+	async setLocation(hashes, location) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		body.set("location", location);
+		await this.post("/api/v2/torrents/setLocation", body);
+	}
+	async rename(hash, name) {
+		const body = new URLSearchParams();
+		body.set("hash", hash);
+		body.set("name", name);
+		await this.post("/api/v2/torrents/rename", body);
+	}
+	async filePrio(hash, fileIds, priority) {
+		const body = new URLSearchParams();
+		body.set("hash", hash);
+		body.set("id", fileIds.join("|"));
+		body.set("priority", String(priority));
+		await this.post("/api/v2/torrents/filePrio", body);
+	}
+	async topPrio(hashes) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		await this.post("/api/v2/torrents/topPrio", body);
+	}
+	async increasePrio(hashes) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		await this.post("/api/v2/torrents/increasePrio", body);
+	}
+	async decreasePrio(hashes) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		await this.post("/api/v2/torrents/decreasePrio", body);
+	}
+	async bottomPrio(hashes) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		await this.post("/api/v2/torrents/bottomPrio", body);
+	}
+	async setForceStart(hashes, value) {
+		const body = new URLSearchParams();
+		body.set("hashes", this.hashes(hashes));
+		body.set("value", String(value));
+		await this.post("/api/v2/torrents/setForceStart", body);
+	}
+	async torrentPeers(hash, rid) {
+		const params = { hash };
+		if (rid !== void 0) params.rid = String(rid);
+		return this.get("/api/v2/sync/torrentPeers", params);
+	}
+	async transferInfo() {
+		return this.get("/api/v2/transfer/info");
+	}
+	async speedLimitsMode() {
+		const result = await this.get("/api/v2/transfer/speedLimitsMode");
+		return Number(result);
+	}
+	async toggleSpeedLimitsMode() {
+		await this.post("/api/v2/transfer/toggleSpeedLimitsMode");
+	}
+	async setGlobalDownloadLimit(limit) {
+		const body = new URLSearchParams();
+		body.set("limit", String(limit));
+		await this.post("/api/v2/transfer/setDownloadLimit", body);
+	}
+	async setGlobalUploadLimit(limit) {
+		const body = new URLSearchParams();
+		body.set("limit", String(limit));
+		await this.post("/api/v2/transfer/setUploadLimit", body);
+	}
+	async version() {
+		return this.get("/api/v2/app/version");
+	}
+	async webapiVersion() {
+		return this.get("/api/v2/app/webapiVersion");
+	}
+	async preferences() {
+		return this.get("/api/v2/app/preferences");
+	}
+	async setPreferences(prefs) {
+		const body = new URLSearchParams();
+		body.set("json", JSON.stringify(prefs));
+		await this.post("/api/v2/app/setPreferences", body);
+	}
+	async defaultSavePath() {
+		return this.get("/api/v2/app/defaultSavePath");
+	}
+	async shutdown() {
+		await this.post("/api/v2/app/shutdown");
+	}
+};
+
+//#endregion
+exports.HTTPError = HTTPError;
+exports.QBittorrentError = QBittorrentError;
+exports.default = QBittorrentClient;

package/dist/index.d.cts

@@ -0,0 +1,62 @@
+import { AddTorrentParams, Preferences, QBittorrentConfig, TorrentFile, TorrentFileInput, TorrentInfo, TorrentInfoParams, TorrentPeer, TorrentPeersResponse, TorrentProperties, TorrentState, TorrentTracker, TransferInfo } from "./schemas.cjs";
+
+//#region src/client.d.ts
+declare class QBittorrentClient {
+  private config;
+  private sid;
+  private loggedIn;
+  private loginPromise;
+  constructor(config: QBittorrentConfig);
+  private baseUrl;
+  private login;
+  private doLogin;
+  private get;
+  private post;
+  private request;
+  private hashes;
+  info(params?: TorrentInfoParams): Promise<TorrentInfo[]>;
+  properties(hash: string): Promise<TorrentProperties>;
+  files(hash: string): Promise<TorrentFile[]>;
+  trackers(hash: string): Promise<TorrentTracker[]>;
+  pieceStates(hash: string): Promise<number[]>;
+  add(params: AddTorrentParams): Promise<void>;
+  delete(hashes: string[], deleteFiles?: boolean): Promise<void>;
+  start(hashes: string[]): Promise<void>;
+  stop(hashes: string[]): Promise<void>;
+  recheck(hashes: string[]): Promise<void>;
+  reannounce(hashes: string[]): Promise<void>;
+  setDownloadLimit(hashes: string[], limit: number): Promise<void>;
+  setUploadLimit(hashes: string[], limit: number): Promise<void>;
+  setShareLimits(hashes: string[], ratioLimit: number, seedingTimeLimit: number, inactiveSeedingTimeLimit: number): Promise<void>;
+  setLocation(hashes: string[], location: string): Promise<void>;
+  rename(hash: string, name: string): Promise<void>;
+  filePrio(hash: string, fileIds: number[], priority: number): Promise<void>;
+  topPrio(hashes: string[]): Promise<void>;
+  increasePrio(hashes: string[]): Promise<void>;
+  decreasePrio(hashes: string[]): Promise<void>;
+  bottomPrio(hashes: string[]): Promise<void>;
+  setForceStart(hashes: string[], value: boolean): Promise<void>;
+  torrentPeers(hash: string, rid?: number): Promise<TorrentPeersResponse>;
+  transferInfo(): Promise<TransferInfo>;
+  speedLimitsMode(): Promise<number>;
+  toggleSpeedLimitsMode(): Promise<void>;
+  setGlobalDownloadLimit(limit: number): Promise<void>;
+  setGlobalUploadLimit(limit: number): Promise<void>;
+  version(): Promise<string>;
+  webapiVersion(): Promise<string>;
+  preferences(): Promise<Preferences>;
+  setPreferences(prefs: Partial<Preferences>): Promise<void>;
+  defaultSavePath(): Promise<string>;
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/error.d.ts
+declare class HTTPError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string);
+}
+declare class QBittorrentError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { type AddTorrentParams, HTTPError, type Preferences, type QBittorrentConfig, QBittorrentError, type TorrentFile, type TorrentFileInput, type TorrentInfo, type TorrentInfoParams, type TorrentPeer, type TorrentPeersResponse, type TorrentProperties, type TorrentState, type TorrentTracker, type TransferInfo, QBittorrentClient as default };

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+import { AddTorrentParams, Preferences, QBittorrentConfig, TorrentFile, TorrentFileInput, TorrentInfo, TorrentInfoParams, TorrentPeer, TorrentPeersResponse, TorrentProperties, TorrentState, TorrentTracker, TransferInfo } from "./schemas.mjs";
+
+//#region src/client.d.ts
+declare class QBittorrentClient {
+  private config;
+  private sid;
+  private loggedIn;
+  private loginPromise;
+  constructor(config: QBittorrentConfig);
+  private baseUrl;
+  private login;
+  private doLogin;
+  private get;
+  private post;
+  private request;
+  private hashes;
+  info(params?: TorrentInfoParams): Promise<TorrentInfo[]>;
+  properties(hash: string): Promise<TorrentProperties>;
+  files(hash: string): Promise<TorrentFile[]>;
+  trackers(hash: string): Promise<TorrentTracker[]>;
+  pieceStates(hash: string): Promise<number[]>;
+  add(params: AddTorrentParams): Promise<void>;
+  delete(hashes: string[], deleteFiles?: boolean): Promise<void>;
+  start(hashes: string[]): Promise<void>;
+  stop(hashes: string[]): Promise<void>;
+  recheck(hashes: string[]): Promise<void>;
+  reannounce(hashes: string[]): Promise<void>;
+  setDownloadLimit(hashes: string[], limit: number): Promise<void>;
+  setUploadLimit(hashes: string[], limit: number): Promise<void>;
+  setShareLimits(hashes: string[], ratioLimit: number, seedingTimeLimit: number, inactiveSeedingTimeLimit: number): Promise<void>;
+  setLocation(hashes: string[], location: string): Promise<void>;
+  rename(hash: string, name: string): Promise<void>;
+  filePrio(hash: string, fileIds: number[], priority: number): Promise<void>;
+  topPrio(hashes: string[]): Promise<void>;
+  increasePrio(hashes: string[]): Promise<void>;
+  decreasePrio(hashes: string[]): Promise<void>;
+  bottomPrio(hashes: string[]): Promise<void>;
+  setForceStart(hashes: string[], value: boolean): Promise<void>;
+  torrentPeers(hash: string, rid?: number): Promise<TorrentPeersResponse>;
+  transferInfo(): Promise<TransferInfo>;
+  speedLimitsMode(): Promise<number>;
+  toggleSpeedLimitsMode(): Promise<void>;
+  setGlobalDownloadLimit(limit: number): Promise<void>;
+  setGlobalUploadLimit(limit: number): Promise<void>;
+  version(): Promise<string>;
+  webapiVersion(): Promise<string>;
+  preferences(): Promise<Preferences>;
+  setPreferences(prefs: Partial<Preferences>): Promise<void>;
+  defaultSavePath(): Promise<string>;
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region src/error.d.ts
+declare class HTTPError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string);
+}
+declare class QBittorrentError extends Error {
+  constructor(message: string);
+}
+//#endregion
+export { type AddTorrentParams, HTTPError, type Preferences, type QBittorrentConfig, QBittorrentError, type TorrentFile, type TorrentFileInput, type TorrentInfo, type TorrentInfoParams, type TorrentPeer, type TorrentPeersResponse, type TorrentProperties, type TorrentState, type TorrentTracker, type TransferInfo, QBittorrentClient as default };