@ctrl/qbittorrent 9.1.0 → 9.3.0

package/README.md

@@ -98,6 +98,15 @@ const result = await client.normalizedAddTorrent(fs.readFileSync(torrentFile), {
 console.log(result);
 ```
 
+##### export and create from state
+
+If you're shutting down the server often (serverless?) you can export the state
+
+```ts
+const state = client.exportState()
+const client = QBittorrent.createFromState(config, state);
+```
+
 ### See Also
 
 All of the following npm modules provide the same normalized functions along with supporting the unique apis for each client.

package/dist/src/qbittorrent.d.ts

@@ -1,16 +1,34 @@
-import type { AddTorrentOptions as NormalizedAddTorrentOptions, AllClientData, NormalizedTorrent, TorrentClient, TorrentSettings } from '@ctrl/shared-torrent';
-import type { AddMagnetOptions, AddTorrentOptions, BuildInfo, Preferences, Torrent, TorrentCategories, TorrentFile, TorrentFilePriority, TorrentFilters, TorrentPeersResponse, TorrentPieceState, TorrentProperties, TorrentTrackers, WebSeed } from './types.js';
+import type { Jsonify } from 'type-fest';
+import type { AddTorrentOptions as NormalizedAddTorrentOptions, AllClientData, NormalizedTorrent, TorrentClient, TorrentClientConfig, TorrentClientState } from '@ctrl/shared-torrent';
+import type { AddMagnetOptions, AddTorrentOptions, BuildInfo, DownloadSpeed, Preferences, Torrent, TorrentCategories, TorrentFile, TorrentFilePriority, TorrentFilters, TorrentPeersResponse, TorrentPieceState, TorrentProperties, TorrentTrackers, UploadSpeed, WebSeed } from './types.js';
+interface QBittorrentState extends TorrentClientState {
+    auth?: {
+        /**
+         * auth cookie
+         */
+        sid: string;
+        /**
+         * cookie expiration
+         */
+        expires: Date;
+    };
+    version?: {
+        version: string;
+        isVersion5OrHigher: boolean;
+    };
+}
 export declare class QBittorrent implements TorrentClient {
-    config: TorrentSettings;
     /**
-     * auth cookie
+     * Create a new QBittorrent client from a state
      */
-    private _sid?;
+    static createFromState(config: Readonly<TorrentClientConfig>, state: Readonly<Jsonify<QBittorrentState>>): QBittorrent;
+    config: TorrentClientConfig;
+    state: QBittorrentState;
+    constructor(options?: Partial<TorrentClientConfig>);
     /**
-     * cookie expiration
+     * Export the state of the client as JSON
      */
-    private _exp?;
-    constructor(options?: Partial<TorrentSettings>);
+    exportState(): Jsonify<QBittorrentState>;
     /**
      * @deprecated
      */
@@ -30,6 +48,22 @@ export declare class QBittorrent implements TorrentClient {
      */
     getBuildInfo(): Promise<BuildInfo>;
     getTorrent(hash: string): Promise<NormalizedTorrent>;
+    /**
+     * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-download-limit}
+     */
+    getTorrentDownloadLimit(hash: string | string[]): Promise<DownloadSpeed>;
+    /**
+     * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#set-torrent-download-limit}
+     */
+    setTorrentDownloadLimit(hash: string | string[], limitBytesPerSecond: number): Promise<boolean>;
+    /**
+     * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-upload-limit}
+     */
+    getTorrentUploadLimit(hash: string | string[]): Promise<UploadSpeed>;
+    /**
+     * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#set-torrent-upload-limit}
+     */
+    setTorrentUploadLimit(hash: string | string[], limitBytesPerSecond: number): Promise<boolean>;
     /**
      * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-application-preferences}
      */
@@ -212,4 +246,6 @@ export declare class QBittorrent implements TorrentClient {
     login(): Promise<boolean>;
     logout(): boolean;
     request<T>(path: string, method: 'GET' | 'POST', params?: Record<string, string | number>, body?: URLSearchParams | FormData, headers?: Record<string, string>, isJson?: boolean): Promise<T>;
+    private checkVersion;
 }
+export {};

package/dist/src/qbittorrent.js

@@ -14,18 +14,28 @@ const defaults = {
     timeout: 5000,
 };
 export class QBittorrent {
-    config;
-    /**
-     * auth cookie
-     */
-    _sid;
     /**
-     * cookie expiration
+     * Create a new QBittorrent client from a state
      */
-    _exp;
+    static createFromState(config, state) {
+        const client = new QBittorrent(config);
+        client.state = {
+            ...state,
+            auth: state.auth ? { ...state.auth, expires: new Date(state.auth.expires) } : undefined,
+        };
+        return client;
+    }
+    config;
+    state = {};
     constructor(options = {}) {
         this.config = { ...defaults, ...options };
     }
+    /**
+     * Export the state of the client as JSON
+     */
+    exportState() {
+        return JSON.parse(JSON.stringify(this.state));
+    }
     /**
      * @deprecated
      */
@@ -66,6 +76,46 @@ export class QBittorrent {
         }
         return normalizeTorrentData(torrentData);
     }
+    /**
+     * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-download-limit}
+     */
+    async getTorrentDownloadLimit(hash) {
+        const downloadLimit = await this.request('/torrents/downloadLimit', 'POST', undefined, objToUrlSearchParams({
+            hashes: normalizeHashes(hash),
+        }), undefined);
+        return downloadLimit;
+    }
+    /**
+     * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#set-torrent-download-limit}
+     */
+    async setTorrentDownloadLimit(hash, limitBytesPerSecond) {
+        const data = {
+            limit: limitBytesPerSecond.toString(),
+            hashes: normalizeHashes(hash),
+        };
+        await this.request('/torrents/setDownloadLimit', 'POST', undefined, objToUrlSearchParams(data));
+        return true;
+    }
+    /**
+     * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-upload-limit}
+     */
+    async getTorrentUploadLimit(hash) {
+        const UploadLimit = await this.request('/torrents/uploadLimit', 'POST', undefined, objToUrlSearchParams({
+            hashes: normalizeHashes(hash),
+        }), undefined);
+        return UploadLimit;
+    }
+    /**
+     * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#set-torrent-upload-limit}
+     */
+    async setTorrentUploadLimit(hash, limitBytesPerSecond) {
+        const data = {
+            limit: limitBytesPerSecond.toString(),
+            hashes: normalizeHashes(hash),
+        };
+        await this.request('/torrents/setUploadLimit', 'POST', undefined, objToUrlSearchParams(data));
+        return true;
+    }
     /**
      * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-application-preferences}
      */
@@ -307,16 +357,20 @@ export class QBittorrent {
      * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#pause-torrents}
      */
     async pauseTorrent(hashes) {
+        const endpoint = this.state.version?.isVersion5OrHigher ? '/torrents/stop' : '/torrents/pause';
         const data = { hashes: normalizeHashes(hashes) };
-        await this.request('/torrents/pause', 'POST', undefined, objToUrlSearchParams(data));
+        await this.request(endpoint, 'POST', undefined, objToUrlSearchParams(data));
         return true;
     }
     /**
      * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#resume-torrents}
      */
     async resumeTorrent(hashes) {
+        const endpoint = this.state.version?.isVersion5OrHigher
+            ? '/torrents/start'
+            : '/torrents/resume';
         const data = { hashes: normalizeHashes(hashes) };
-        await this.request('/torrents/resume', 'POST', undefined, objToUrlSearchParams(data));
+        await this.request(endpoint, 'POST', undefined, objToUrlSearchParams(data));
         return true;
     }
     /**
@@ -362,6 +416,11 @@ export class QBittorrent {
             form.set('file', file);
         }
         if (options) {
+            // Handle version-specific paused/stopped parameter
+            if (this.state.version?.isVersion5OrHigher && 'paused' in options) {
+                form.append('stopped', options.paused);
+                delete options.paused;
+            }
             // disable savepath when autoTMM is defined
             if (options.useAutoTMM === 'true') {
                 options.savepath = '';
@@ -436,6 +495,11 @@ export class QBittorrent {
         const form = new FormData();
         form.append('urls', urls);
         if (options) {
+            // Handle version-specific paused/stopped parameter
+            if (this.state.version?.isVersion5OrHigher && 'paused' in options) {
+                form.append('stopped', options.paused);
+                delete options.paused;
+            }
             // disable savepath when autoTMM is defined
             if (options.useAutoTMM === 'true') {
                 options.savepath = '';
@@ -526,7 +590,7 @@ export class QBittorrent {
      * {@link https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#login}
      */
     async login() {
-        const url = joinURL(this.config.baseUrl, this.config.path, '/auth/login');
+        const url = joinURL(this.config.baseUrl, this.config.path ?? '', '/auth/login');
         const res = await ofetch.raw(url, {
             method: 'POST',
             headers: {
@@ -544,41 +608,43 @@ export class QBittorrent {
         if (!res.headers.get('set-cookie')?.length) {
             throw new Error('Cookie not found. Auth Failed.');
         }
-        const cookie = cookieParse(res.headers.get('set-cookie'));
+        const cookie = cookieParse(res.headers.get('set-cookie') ?? '');
         if (!cookie.SID) {
             throw new Error('Invalid cookie');
         }
-        this._sid = cookie.SID;
-        // Not sure if it might be lowercase
         const expires = cookie.Expires ?? cookie.expires;
-        // Assumed to be in seconds
         const maxAge = cookie['Max-Age'] ?? cookie['max-age'];
-        this._exp = expires
-            ? new Date(expires)
-            : maxAge
-                ? new Date(Number(maxAge) * 1000)
-                : // Default expiration 1 hour
-                    new Date(Date.now() + 3600000);
+        this.state.auth = {
+            sid: cookie.SID,
+            expires: expires
+                ? new Date(expires)
+                : maxAge
+                    ? new Date(Number(maxAge) * 1000)
+                    : new Date(Date.now() + 3600000),
+        };
+        // Check version after successful login
+        await this.checkVersion();
         return true;
     }
     logout() {
-        this._sid = undefined;
-        this._exp = undefined;
+        delete this.state.auth;
         return true;
     }
     // eslint-disable-next-line max-params
     async request(path, method, params, body, headers = {}, isJson = true) {
-        if (!this._sid || !this._exp || this._exp.getTime() < new Date().getTime()) {
+        if (!this.state.auth?.sid ||
+            !this.state.auth.expires ||
+            this.state.auth.expires.getTime() < new Date().getTime()) {
             const authed = await this.login();
             if (!authed) {
                 throw new Error('Auth Failed');
             }
         }
-        const url = joinURL(this.config.baseUrl, this.config.path, path);
+        const url = joinURL(this.config.baseUrl, this.config.path ?? '', path);
         const res = await ofetch(url, {
             method,
             headers: {
-                Cookie: `SID=${this._sid ?? ''}`,
+                Cookie: `SID=${this.state.auth.sid ?? ''}`,
                 ...headers,
             },
             body,
@@ -592,6 +658,17 @@ export class QBittorrent {
         });
         return res;
     }
+    async checkVersion() {
+        if (!this.state.version?.version) {
+            const newVersion = await this.getAppVersion();
+            // Remove potential 'v' prefix and any extra info after version number
+            const cleanVersion = newVersion.replace(/^v/, '').split('-')[0];
+            this.state.version = {
+                version: newVersion,
+                isVersion5OrHigher: cleanVersion === '5.0.0' || isGreater(cleanVersion, '5.0.0'),
+            };
+        }
+    }
 }
 /**
  * Normalizes hashes
@@ -610,3 +687,6 @@ function objToUrlSearchParams(obj) {
     }
     return params;
 }
+function isGreater(a, b) {
+    return a.localeCompare(b, undefined, { numeric: true }) === 1;
+}

package/dist/src/types.d.ts

@@ -549,7 +549,8 @@ export interface AddTorrentOptions {
     /**
      * Add torrents in the paused state. Possible values are true, false (default)
      */
-    paused: TrueFalseStr;
+    paused?: TrueFalseStr;
+    stopped?: TrueFalseStr;
     /**
      * Control filesystem structure for content (added in Web API v2.7)
      * Migrating from rootFolder example rootFolder ? 'Original' :  'NoSubfolder'
@@ -606,7 +607,8 @@ export interface AddMagnetOptions {
     /**
      * Add torrents in the paused state. Possible values are true, false (default)
      */
-    paused: TrueFalseStr;
+    paused?: TrueFalseStr;
+    stopped?: TrueFalseStr;
     /**
      * Create the root folder. Possible values are true, false, unset (default)
      */
@@ -1266,4 +1268,6 @@ export interface TorrentPeer {
     up_speed?: number;
     uploaded?: number;
 }
+export type DownloadSpeed = Record<string, number>;
+export type UploadSpeed = Record<string, number>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl/qbittorrent",
-  "version": "9.1.0",
+  "version": "9.3.0",
   "description": "TypeScript api wrapper for qbittorrent using got",
   "author": "Scott Cooper <scttcper@gmail.com>",
   "license": "MIT",
@@ -37,26 +37,28 @@
   },
   "dependencies": {
     "@ctrl/magnet-link": "^4.0.2",
-    "@ctrl/shared-torrent": "^6.1.0",
+    "@ctrl/shared-torrent": "^6.2.1",
     "@ctrl/torrent-file": "^4.1.0",
-    "cookie": "^1.0.1",
-    "node-fetch-native": "^1.6.4",
+    "cookie": "^1.0.2",
+    "node-fetch-native": "^1.6.6",
     "ofetch": "^1.4.1",
+    "type-fest": "^4.34.1",
     "ufo": "^1.5.4",
     "uint8array-extras": "^1.4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
-    "@ctrl/eslint-config-biome": "4.2.11",
-    "@eslint/compat": "^1.2.2",
-    "@sindresorhus/tsconfig": "6.0.0",
+    "@ctrl/eslint-config-biome": "4.3.2",
+    "@eslint/compat": "^1.2.6",
+    "@sindresorhus/tsconfig": "7.0.0",
     "@types/cookie": "1.0.0",
-    "@types/node": "22.9.0",
-    "@vitest/coverage-v8": "2.1.4",
+    "@types/node": "22.13.1",
+    "@vitest/coverage-v8": "3.0.5",
+    "eslint": "^9.20.1",
     "p-wait-for": "5.0.2",
-    "typedoc": "0.26.11",
-    "typescript": "5.6.3",
-    "vitest": "2.1.4"
+    "typedoc": "0.27.7",
+    "typescript": "5.7.3",
+    "vitest": "3.0.5"
   },
   "release": {
     "branches": [