@ctrl/rqbit 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Scott Cooper <scttcper@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# rqbit [![npm](https://img.shields.io/npm/v/@ctrl/rqbit.svg?maxAge=3600)](https://www.npmjs.com/package/@ctrl/rqbit)
+
+> TypeScript api wrapper for [rqbit](https://github.com/ikatson/rqbit) using [ofetch](https://github.com/unjs/ofetch)
+
+### Install
+
+```sh
+npm install @ctrl/rqbit
+```
+
+### Use
+
+```ts
+import { Rqbit } from '@ctrl/rqbit';
+
+const client = new Rqbit({
+  baseUrl: 'http://localhost:3030/',
+  // only needed when rqbit is started with RQBIT_HTTP_BASIC_AUTH_USERPASS
+  username: 'admin',
+  password: 'adminadmin',
+});
+
+async function main() {
+  const res = await client.getAllData();
+  console.log(res);
+}
+```
+
+### API
+
+Docs: https://rqbit.ep.workers.dev
+
+rqbit has no published api reference, `GET /` on the server lists every endpoint (`client.getApiInfo()`). The types here are based on responses from rqbit 9.0.1 and its [http api source](https://github.com/ikatson/rqbit/tree/v9.0.1/crates/librqbit/src/http_api).
+
+Things that work differently from the other clients:
+
+- Adding a magnet does not respond until rqbit resolves the metadata from peers. Adds use `addTimeout` (default 60 seconds) instead of `timeout`.
+- rqbit has no labels, queue, or added/completed dates. `label` is ignored, `queueUp`/`queueDown` throw, and `dateAdded` is an empty string.
+- `createTorrent` needs rqbit started with `RQBIT_HTTP_API_ALLOW_CREATE=true`, and `getStreamUrl`/`getPlaylistUrl` urls need the same basic auth as the api.
+- Speeds are reported in MiB/s and converted to bytes per second when normalized.
+- Torrents are added with `overwrite: true` by default, like Radarr does. rqbit refuses to add a torrent whose files already exist on disk otherwise.
+- Failed requests throw `RqbitApiError` with the http `status` and rqbit's error `kind`, ex - `torrent_not_found`. Timeouts and network errors are also `RqbitApiError` with no `status`.
+- rqbit's `total_bytes` only counts the pieces of selected files. `getTorrent` uses the file list for `totalSize`, `getAllData` skips the extra request per torrent so its `totalSize` is the selected size.
+
+### Normalized API
+
+These functions are normalized through [@ctrl/shared-torrent](https://github.com/scttcper/shared-torrent), which makes it easier to support multiple torrent clients. See [below](#see-also) for alternative supported torrent clients.
+
+##### getAllData
+
+Returns all torrent data and an array of label objects. Data has been normalized and does not match the output of native `listTorrents()`. rqbit has no labels so labels is always empty.
+
+```ts
+const data = await client.getAllData();
+console.log(data.torrents);
+```
+
+##### getTorrent
+
+Returns one torrent data from torrent hash
+
+```ts
+const data = await client.getTorrent('torrent-hash');
+console.log(data);
+```
+
+##### pauseTorrent and resumeTorrent
+
+Pause or resume a torrent
+
+```ts
+const paused = await client.pauseTorrent('torrent-hash');
+console.log(paused);
+const resumed = await client.resumeTorrent('torrent-hash');
+console.log(resumed);
+```
+
+##### removeTorrent
+
+Remove a torrent. Does not remove data on disk by default.
+
+```ts
+// does not remove data on disk
+const result = await client.removeTorrent('torrent-hash', false);
+console.log(result);
+
+// remove data on disk
+const res = await client.removeTorrent('torrent-hash', true);
+console.log(res);
+```
+
+##### addTorrent
+
+Add a torrent from a magnet link or torrent file, has client specific options. Also see normalizedAddTorrent
+
+```ts
+import { readFileSync } from 'node:fs';
+
+const result = await client.addTorrent(new Uint8Array(readFileSync('./linux.torrent')), {
+  output_folder: '/downloads/linux',
+});
+console.log(result.details.info_hash);
+```
+
+##### normalizedAddTorrent
+
+Add a torrent and return normalized torrent data. rqbit cannot add a torrent paused, `startPaused` pauses it right after adding.
+
+```ts
+const result = await client.normalizedAddTorrent('magnet:?xt=urn:btih:...', {
+  startPaused: true,
+});
+console.log(result);
+```
+
+##### export and create from state
+
+rqbit uses basic auth on every request so there is no session to save, this exists to match the other clients.
+
+```ts
+const state = client.exportState();
+const restored = Rqbit.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.
+
+- shared types - [@ctrl/shared-torrent](https://github.com/scttcper/shared-torrent)
+- deluge - [@ctrl/deluge](https://github.com/scttcper/deluge)
+- transmission - [@ctrl/transmission](https://github.com/scttcper/transmission)
+- qbittorrent - [@ctrl/qbittorrent](https://github.com/scttcper/qbittorrent)
+- utorrent - [@ctrl/utorrent](https://github.com/scttcper/utorrent)
+- rtorrent - [@ctrl/rtorrent](https://github.com/scttcper/rtorrent)
+
+Usenet clients with the same normalized approach:
+
+- usenet shared types - [@ctrl/shared-usenet](https://github.com/scttcper/shared-usenet)
+- nzbget - [@ctrl/nzbget](https://github.com/scttcper/nzbget)
+- sabnzbd - [@ctrl/sabnzbd](https://github.com/scttcper/sabnzbd)
+
+### Start a test docker container
+
+```
+docker run -d \
+  --name=rqbit \
+  -e RQBIT_HTTP_BASIC_AUTH_USERPASS=admin:adminadmin \
+  -e RQBIT_HTTP_API_ALLOW_CREATE=true \
+  -p 3030:3030 \
+  -p 4240:4240 \
+  -v ~/Documents/rqbit/downloads:/home/rqbit/downloads \
+  --restart unless-stopped \
+  ikatson/rqbit:latest
+```

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export * from './rqbit.js';
+export * from './normalizeTorrentData.js';
+export type * from './types.js';

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export * from './rqbit.js';
+export * from './normalizeTorrentData.js';

package/dist/src/normalizeTorrentData.d.ts

@@ -0,0 +1,11 @@
+import { type NormalizedTorrent } from '@ctrl/shared-torrent';
+import type { TorrentFile, TorrentWithStats } from './types.js';
+/**
+ * Convert a torrent with stats into the shared normalized format.
+ * Speeds are MiB/s and the ETA is a `{ secs, nanos }` duration,
+ * see {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/torrent_state/stats.rs}
+ *
+ * @param files file list from the torrent details, used for `totalSize`.
+ * rqbit's `total_bytes` only counts the pieces of selected files, so without the file list `totalSize` is the selected size.
+ */
+export declare function normalizeTorrentData(torrent: TorrentWithStats, files?: TorrentFile[]): NormalizedTorrent;

package/dist/src/normalizeTorrentData.js

@@ -0,0 +1,65 @@
+import { TorrentState } from '@ctrl/shared-torrent';
+const MIB = 1024 * 1024;
+/**
+ * Convert a torrent with stats into the shared normalized format.
+ * Speeds are MiB/s and the ETA is a `{ secs, nanos }` duration,
+ * see {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/torrent_state/stats.rs}
+ *
+ * @param files file list from the torrent details, used for `totalSize`.
+ * rqbit's `total_bytes` only counts the pieces of selected files, so without the file list `totalSize` is the selected size.
+ */
+export function normalizeTorrentData(torrent, files) {
+    const { stats } = torrent;
+    const live = stats.live;
+    let state = TorrentState.unknown;
+    switch (stats.state) {
+        case 'initializing': {
+            // pausing during initialization keeps the torrent in initializing until it is started
+            state = stats.initializing_paused ? TorrentState.paused : TorrentState.checking;
+            break;
+        }
+        case 'live': {
+            state = stats.finished ? TorrentState.seeding : TorrentState.downloading;
+            break;
+        }
+        case 'paused': {
+            state = TorrentState.paused;
+            break;
+        }
+        case 'error': {
+            state = TorrentState.error;
+            break;
+        }
+    }
+    const progress = stats.total_bytes > 0 ? stats.progress_bytes / stats.total_bytes : 0;
+    const peerStats = live?.snapshot.peer_stats;
+    return {
+        id: torrent.info_hash,
+        name: torrent.name ?? torrent.info_hash,
+        state,
+        stateMessage: stats.error ?? '',
+        isCompleted: stats.finished,
+        progress,
+        ratio: stats.progress_bytes > 0 ? stats.uploaded_bytes / stats.progress_bytes : 0,
+        // rqbit does not track when a torrent was added or completed
+        dateAdded: '',
+        dateCompleted: undefined,
+        label: undefined,
+        savePath: torrent.output_folder,
+        uploadSpeed: live ? Math.round(live.upload_speed.mbps * MIB) : 0,
+        downloadSpeed: live ? Math.round(live.download_speed.mbps * MIB) : 0,
+        eta: live?.time_remaining?.duration.secs ?? 0,
+        // rqbit has no queue
+        queuePosition: 0,
+        // rqbit does not report seeds separately from peers
+        connectedPeers: peerStats?.live ?? 0,
+        connectedSeeds: 0,
+        totalPeers: peerStats?.seen ?? 0,
+        totalSeeds: 0,
+        totalSelected: stats.total_bytes,
+        totalSize: files ? files.reduce((sum, file) => sum + file.length, 0) : stats.total_bytes,
+        totalUploaded: stats.uploaded_bytes,
+        totalDownloaded: stats.progress_bytes,
+        raw: torrent,
+    };
+}

package/dist/src/rqbit.d.ts

@@ -0,0 +1,156 @@
+import type { AddTorrentOptions as NormalizedAddTorrentOptions, AllClientData, NormalizedTorrent, TorrentClient, TorrentClientConfig, TorrentClientState } from '@ctrl/shared-torrent';
+import { type FetchOptions, type MappedResponseType, type ResponseType } from 'ofetch';
+import type { Jsonify } from 'type-fest';
+import type { AddTorrentOptions, AddTorrentResponse, ApiRootResponse, CreateTorrentOptions, CreateTorrentResponse, DhtStats, EmptyResponse, ListTorrentsResponse, PeerStatsResponse, RateLimits, RqbitErrorResponse, SessionStats, TorrentDetails, TorrentIdOrHash, TorrentListItem, TorrentStats, TorrentWithStats } from './types.js';
+/**
+ * rqbit uses basic auth on every request, there is no session to keep
+ */
+export type RqbitState = TorrentClientState;
+export interface RqbitConfig extends TorrentClientConfig {
+    /**
+     * How long to wait when adding a torrent, in milliseconds.
+     * rqbit does not respond to an add until magnet metadata is resolved from peers, so adds need much longer than `timeout`.
+     * default: 60_000
+     */
+    addTimeout?: number;
+}
+export type ResolvedConfig = RqbitConfig & {
+    path: string;
+    addTimeout: number;
+};
+/**
+ * Error thrown when a request to rqbit fails, either an error response or a timeout/network error
+ */
+export declare class RqbitApiError extends Error {
+    name: string;
+    /**
+     * HTTP status code, undefined when no response was received (timeout or network error)
+     */
+    status?: number;
+    /**
+     * rqbit error kind, ex - `torrent_not_found`. Undefined when rqbit returned a plain text error.
+     */
+    kind?: string;
+    response?: RqbitErrorResponse;
+    constructor(status: number | undefined, message: string, response?: RqbitErrorResponse, cause?: unknown);
+}
+/**
+ * rqbit has no published api reference. `GET /` on the server lists every endpoint, see {@link Rqbit.getApiInfo}.
+ * Routes {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api/handlers/mod.rs}
+ * Response types {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/api.rs}
+ */
+export declare class Rqbit implements TorrentClient {
+    static createFromState(config: Readonly<Partial<RqbitConfig>>, state: Readonly<Jsonify<RqbitState>>): Rqbit;
+    config: ResolvedConfig;
+    state: RqbitState;
+    constructor(options?: Partial<RqbitConfig>);
+    exportState(): Jsonify<RqbitState>;
+    /**
+     * Lists the available api endpoints and the rqbit version
+     */
+    getApiInfo(): Promise<ApiRootResponse>;
+    /**
+     * rqbit version, ex - `9.0.1`
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Session wide download/upload speed, peer and connection stats
+     */
+    getSessionStats(): Promise<SessionStats>;
+    getDhtStats(): Promise<DhtStats>;
+    getRateLimits(): Promise<RateLimits>;
+    /**
+     * Set session wide rate limits in bytes per second, null removes the limit
+     */
+    setRateLimits(limits: RateLimits): Promise<EmptyResponse>;
+    listTorrents(withStats: true): Promise<ListTorrentsResponse<TorrentWithStats>>;
+    listTorrents(withStats?: false): Promise<ListTorrentsResponse<TorrentListItem>>;
+    /**
+     * Torrent details including the file list
+     */
+    getTorrentDetails(id: TorrentIdOrHash): Promise<TorrentDetails>;
+    getTorrentStats(id: TorrentIdOrHash): Promise<TorrentStats>;
+    /**
+     * Per peer stats, defaults to only live peers
+     */
+    getTorrentPeerStats(id: TorrentIdOrHash, state?: 'live' | 'all'): Promise<PeerStatsResponse>;
+    /**
+     * Download the .torrent file for a torrent
+     */
+    getTorrentMetadata(id: TorrentIdOrHash): Promise<Uint8Array<ArrayBuffer>>;
+    /**
+     * Url to stream a file from a torrent, supports range requests. rqbit requires basic auth on this url when it is enabled.
+     * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api/handlers/streaming.rs}
+     * @param fileIndex index into the torrent's file list
+     */
+    getStreamUrl(id: TorrentIdOrHash, fileIndex: number): string;
+    /**
+     * Url to an m3u8 playlist of a torrent's playable files, or every torrent's when no id is passed.
+     * rqbit requires basic auth on this url when it is enabled.
+     */
+    getPlaylistUrl(id?: TorrentIdOrHash): string;
+    pauseTorrent(id: TorrentIdOrHash): Promise<EmptyResponse>;
+    resumeTorrent(id: TorrentIdOrHash): Promise<EmptyResponse>;
+    /**
+     * Remove a torrent
+     * @param removeData (default: false) If true, remove the downloaded files.
+     */
+    removeTorrent(id: TorrentIdOrHash, removeData?: boolean): Promise<EmptyResponse>;
+    /**
+     * Change which files are downloaded
+     * @param fileIds indexes into the torrent's file list
+     */
+    setTorrentFiles(id: TorrentIdOrHash, fileIds: number[]): Promise<EmptyResponse>;
+    /**
+     * Connect to additional peers
+     * @param peers ex - `['1.2.3.4:6881']`
+     */
+    addPeers(id: TorrentIdOrHash, peers: string[]): Promise<{
+        added: number;
+    }>;
+    /**
+     * rqbit does not support queueing
+     */
+    queueUp(_id: TorrentIdOrHash): Promise<never>;
+    /**
+     * rqbit does not support queueing
+     */
+    queueDown(_id: TorrentIdOrHash): Promise<never>;
+    /**
+     * Add a magnet link or a url to a .torrent file.
+     * rqbit resolves magnet metadata from peers before it responds, so this can take a while, see {@link RqbitConfig.addTimeout}
+     * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api/handlers/torrents.rs}
+     */
+    addMagnet(url: string, options?: Partial<AddTorrentOptions>): Promise<AddTorrentResponse>;
+    /**
+     * Add a torrent
+     * @param torrent .torrent file contents, or the file contents as a base64 string. Magnet links and urls are passed to {@link Rqbit.addMagnet}
+     */
+    addTorrent(torrent: string | Uint8Array<ArrayBuffer>, options?: Partial<AddTorrentOptions>): Promise<AddTorrentResponse>;
+    /**
+     * Resolve a magnet link to .torrent file contents without adding it.
+     * Like adding, rqbit fetches the metadata from peers before it responds, see {@link RqbitConfig.addTimeout}
+     */
+    resolveMagnet(magnet: string, options?: Partial<Pick<AddTorrentOptions, 'timeout_ms'>>): Promise<Uint8Array<ArrayBuffer>>;
+    /**
+     * Create a torrent from a folder on the rqbit server and start seeding it.
+     * rqbit must be started with `--http-api-allow-create` or `RQBIT_HTTP_API_ALLOW_CREATE=true`.
+     * @param folder path to the folder on the rqbit server
+     */
+    createTorrent(folder: string, options?: Partial<CreateTorrentOptions>): Promise<CreateTorrentResponse>;
+    /**
+     * Add a torrent and return normalized torrent data.
+     * The add endpoint has no paused option, `startPaused` pauses the torrent after adding.
+     * rqbit does not support labels, `label` is ignored.
+     * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api_types.rs}
+     */
+    normalizedAddTorrent(torrent: string | Uint8Array<ArrayBuffer>, options?: Partial<NormalizedAddTorrentOptions>): Promise<NormalizedTorrent>;
+    getTorrent(id: TorrentIdOrHash): Promise<NormalizedTorrent>;
+    /**
+     * rqbit does not support labels so labels is always empty
+     */
+    getAllData(): Promise<AllClientData>;
+    request<T, R extends ResponseType = 'json'>(path: string, options?: FetchOptions<R>): Promise<MappedResponseType<R, T>>;
+    private url;
+    private postTorrent;
+}

package/dist/src/rqbit.js

@@ -0,0 +1,338 @@
+import { FetchError, ofetch, } from 'ofetch';
+import { joinURL } from 'ufo';
+import { base64ToUint8Array, stringToBase64 } from 'uint8array-extras';
+import { normalizeTorrentData } from './normalizeTorrentData.js';
+const defaults = {
+    baseUrl: 'http://localhost:3030/',
+    path: '/',
+    username: '',
+    password: '',
+    timeout: 5000,
+    addTimeout: 60_000,
+};
+/**
+ * Error thrown when a request to rqbit fails, either an error response or a timeout/network error
+ */
+export class RqbitApiError extends Error {
+    name = 'RqbitApiError';
+    /**
+     * HTTP status code, undefined when no response was received (timeout or network error)
+     */
+    status;
+    /**
+     * rqbit error kind, ex - `torrent_not_found`. Undefined when rqbit returned a plain text error.
+     */
+    kind;
+    response;
+    constructor(status, message, response, cause) {
+        super(message, { cause });
+        this.status = status;
+        this.kind = response?.error_kind;
+        this.response = response;
+    }
+}
+/**
+ * rqbit has no published api reference. `GET /` on the server lists every endpoint, see {@link Rqbit.getApiInfo}.
+ * Routes {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api/handlers/mod.rs}
+ * Response types {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/api.rs}
+ */
+export class Rqbit {
+    static createFromState(config, state) {
+        const client = new Rqbit(config);
+        client.state = { ...state };
+        return client;
+    }
+    config;
+    state = {};
+    constructor(options = {}) {
+        this.config = { ...defaults, ...options };
+    }
+    exportState() {
+        return JSON.parse(JSON.stringify(this.state));
+    }
+    /**
+     * Lists the available api endpoints and the rqbit version
+     */
+    async getApiInfo() {
+        return this.request('/');
+    }
+    /**
+     * rqbit version, ex - `9.0.1`
+     */
+    async getVersion() {
+        const res = await this.getApiInfo();
+        return res.version;
+    }
+    /**
+     * Session wide download/upload speed, peer and connection stats
+     */
+    async getSessionStats() {
+        return this.request('/stats');
+    }
+    async getDhtStats() {
+        return this.request('/dht/stats');
+    }
+    async getRateLimits() {
+        return this.request('/torrents/limits');
+    }
+    /**
+     * Set session wide rate limits in bytes per second, null removes the limit
+     */
+    async setRateLimits(limits) {
+        return this.request('/torrents/limits', { method: 'POST', body: limits });
+    }
+    async listTorrents(withStats = false) {
+        return this.request('/torrents', {
+            query: withStats ? { with_stats: true } : undefined,
+        });
+    }
+    /**
+     * Torrent details including the file list
+     */
+    async getTorrentDetails(id) {
+        return this.request(`/torrents/${id}`);
+    }
+    async getTorrentStats(id) {
+        return this.request(`/torrents/${id}/stats/v1`);
+    }
+    /**
+     * Per peer stats, defaults to only live peers
+     */
+    async getTorrentPeerStats(id, state = 'live') {
+        return this.request(`/torrents/${id}/peer_stats`, { query: { state } });
+    }
+    /**
+     * Download the .torrent file for a torrent
+     */
+    async getTorrentMetadata(id) {
+        const res = await this.request(`/torrents/${id}/metadata`, {
+            responseType: 'arrayBuffer',
+        });
+        return new Uint8Array(res);
+    }
+    /**
+     * Url to stream a file from a torrent, supports range requests. rqbit requires basic auth on this url when it is enabled.
+     * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api/handlers/streaming.rs}
+     * @param fileIndex index into the torrent's file list
+     */
+    getStreamUrl(id, fileIndex) {
+        return this.url(`/torrents/${id}/stream/${fileIndex}`);
+    }
+    /**
+     * Url to an m3u8 playlist of a torrent's playable files, or every torrent's when no id is passed.
+     * rqbit requires basic auth on this url when it is enabled.
+     */
+    getPlaylistUrl(id) {
+        return this.url(id === undefined ? '/torrents/playlist' : `/torrents/${id}/playlist`);
+    }
+    async pauseTorrent(id) {
+        return this.request(`/torrents/${id}/pause`, { method: 'POST' });
+    }
+    async resumeTorrent(id) {
+        return this.request(`/torrents/${id}/start`, { method: 'POST' });
+    }
+    /**
+     * Remove a torrent
+     * @param removeData (default: false) If true, remove the downloaded files.
+     */
+    async removeTorrent(id, removeData = false) {
+        const action = removeData ? 'delete' : 'forget';
+        return this.request(`/torrents/${id}/${action}`, { method: 'POST' });
+    }
+    /**
+     * Change which files are downloaded
+     * @param fileIds indexes into the torrent's file list
+     */
+    async setTorrentFiles(id, fileIds) {
+        return this.request(`/torrents/${id}/update_only_files`, {
+            method: 'POST',
+            body: { only_files: fileIds },
+        });
+    }
+    /**
+     * Connect to additional peers
+     * @param peers ex - `['1.2.3.4:6881']`
+     */
+    async addPeers(id, peers) {
+        return this.request(`/torrents/${id}/add_peers`, {
+            method: 'POST',
+            body: peers.join('\n'),
+            headers: { 'Content-Type': 'text/plain' },
+        });
+    }
+    /**
+     * rqbit does not support queueing
+     */
+    async queueUp(_id) {
+        throw new Error('rqbit does not support queueing');
+    }
+    /**
+     * rqbit does not support queueing
+     */
+    async queueDown(_id) {
+        throw new Error('rqbit does not support queueing');
+    }
+    /**
+     * Add a magnet link or a url to a .torrent file.
+     * rqbit resolves magnet metadata from peers before it responds, so this can take a while, see {@link RqbitConfig.addTimeout}
+     * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api/handlers/torrents.rs}
+     */
+    async addMagnet(url, options = {}) {
+        return this.postTorrent(url, true, options);
+    }
+    /**
+     * Add a torrent
+     * @param torrent .torrent file contents, or the file contents as a base64 string. Magnet links and urls are passed to {@link Rqbit.addMagnet}
+     */
+    async addTorrent(torrent, options = {}) {
+        if (typeof torrent === 'string') {
+            if (isUrl(torrent)) {
+                return this.addMagnet(torrent, options);
+            }
+            return this.postTorrent(base64ToUint8Array(torrent), false, options);
+        }
+        return this.postTorrent(torrent, false, options);
+    }
+    /**
+     * Resolve a magnet link to .torrent file contents without adding it.
+     * Like adding, rqbit fetches the metadata from peers before it responds, see {@link RqbitConfig.addTimeout}
+     */
+    async resolveMagnet(magnet, options = {}) {
+        const timeoutMs = options.timeout_ms ?? this.config.addTimeout;
+        const res = await this.request('/torrents/resolve_magnet', {
+            method: 'POST',
+            query: { timeout_ms: timeoutMs },
+            body: magnet,
+            // rqbit returns the torrent decoded as json when asked for json
+            headers: { 'Content-Type': 'text/plain', Accept: 'application/x-bittorrent' },
+            responseType: 'arrayBuffer',
+            timeout: timeoutMs + 5000,
+        });
+        return new Uint8Array(res);
+    }
+    /**
+     * Create a torrent from a folder on the rqbit server and start seeding it.
+     * rqbit must be started with `--http-api-allow-create` or `RQBIT_HTTP_API_ALLOW_CREATE=true`.
+     * @param folder path to the folder on the rqbit server
+     */
+    async createTorrent(folder, options = {}) {
+        const magnet = await this.request('/torrents/create', {
+            method: 'POST',
+            // repeated trackers=a&trackers=b
+            query: { output: 'magnet', ...options },
+            body: folder,
+            headers: { 'Content-Type': 'text/plain' },
+            responseType: 'text',
+        });
+        // rqbit only sends the info hash in the magnet
+        const infoHash = new URL(magnet).searchParams.get('xt').replace('urn:btih:', '');
+        return { magnet, info_hash: infoHash };
+    }
+    /**
+     * Add a torrent and return normalized torrent data.
+     * The add endpoint has no paused option, `startPaused` pauses the torrent after adding.
+     * rqbit does not support labels, `label` is ignored.
+     * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api_types.rs}
+     */
+    async normalizedAddTorrent(torrent, options = {}) {
+        const res = await this.addTorrent(torrent);
+        const hash = res.details.info_hash;
+        if (options.startPaused) {
+            await this.pauseTorrent(hash);
+        }
+        return this.getTorrent(hash);
+    }
+    async getTorrent(id) {
+        const [details, stats] = await Promise.all([
+            this.getTorrentDetails(id),
+            this.getTorrentStats(id),
+        ]);
+        return normalizeTorrentData({
+            id: details.id,
+            info_hash: details.info_hash,
+            name: details.name,
+            output_folder: details.output_folder,
+            total_pieces: details.total_pieces,
+            stats,
+        }, details.files);
+    }
+    /**
+     * rqbit does not support labels so labels is always empty
+     */
+    async getAllData() {
+        const res = await this.listTorrents(true);
+        return {
+            torrents: res.torrents.map(torrent => normalizeTorrentData(torrent)),
+            labels: [],
+            raw: res,
+        };
+    }
+    async request(path, options = {}) {
+        const url = this.url(path);
+        const headers = new Headers(options.headers);
+        if (this.config.username || this.config.password) {
+            const auth = stringToBase64(`${this.config.username}:${this.config.password}`);
+            headers.set('Authorization', `Basic ${auth}`);
+        }
+        try {
+            return await ofetch(url, {
+                timeout: this.config.timeout,
+                dispatcher: this.config.dispatcher,
+                retry: false,
+                ...options,
+                headers,
+            });
+        }
+        catch (error) {
+            if (!(error instanceof FetchError)) {
+                throw error;
+            }
+            if (!error.response) {
+                // ofetch aborted (timeout) or the request never reached rqbit
+                throw new RqbitApiError(undefined, error.message, undefined, error);
+            }
+            const data = error.data;
+            if (isRqbitError(data)) {
+                throw new RqbitApiError(error.response.status, data.human_readable, data, error);
+            }
+            // rqbit returns plain text for routing and query string errors
+            const message = typeof data === 'string' && data ? data : error.message;
+            throw new RqbitApiError(error.response.status, message, undefined, error);
+        }
+    }
+    url(path) {
+        return joinURL(this.config.baseUrl, this.config.path, path);
+    }
+    async postTorrent(body, isUrlBody, options) {
+        const { only_files, initial_peers, ...rest } = options;
+        const timeoutMs = options.timeout_ms ?? this.config.addTimeout;
+        const query = {
+            overwrite: true,
+            is_url: isUrlBody,
+            ...rest,
+            timeout_ms: timeoutMs,
+        };
+        if (only_files) {
+            query.only_files = only_files.join(',');
+        }
+        if (initial_peers) {
+            query.initial_peers = initial_peers.join(',');
+        }
+        return this.request('/torrents', {
+            method: 'POST',
+            query,
+            body,
+            headers: {
+                'Content-Type': isUrlBody ? 'text/plain' : 'application/x-bittorrent',
+            },
+            // leave room for rqbit to respond with its own timeout error
+            timeout: timeoutMs + 5000,
+        });
+    }
+}
+function isUrl(str) {
+    return /^(magnet:|https?:\/\/)/i.test(str);
+}
+function isRqbitError(data) {
+    return typeof data === 'object' && data !== null && 'error_kind' in data;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Types are based on responses from rqbit 9.0.1.
+ * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/api.rs}
+ * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/webui/src/api-types.ts}
+ *
+ * Response from `GET /`
+ */
+export interface ApiRootResponse {
+    /**
+     * Map of `"METHOD /path"` to a description of the endpoint
+     */
+    apis: Record<string, string>;
+    server: 'rqbit';
+    /**
+     * rqbit version, ex - `9.0.1`
+     */
+    version: string;
+}
+/**
+ * Torrent id from rqbit, or the 40 character info hash
+ */
+export type TorrentIdOrHash = number | string;
+/**
+ * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/torrent_state/stats.rs}
+ */
+export interface Speed {
+    /**
+     * Speed in MiB/s (despite the name), multiply by 1024 * 1024 for bytes per second
+     */
+    mbps: number;
+    /**
+     * ex - `7.56 MiB/s`
+     */
+    human_readable: string;
+}
+export interface Duration {
+    secs: number;
+    nanos: number;
+}
+export interface DurationWithHumanReadable {
+    duration: Duration;
+    /**
+     * ex - `4m 1s`
+     */
+    human_readable: string;
+}
+export interface AggregatePeerStats {
+    queued: number;
+    connecting: number;
+    live: number;
+    live_tcp: number;
+    live_utp: number;
+    live_socks: number;
+    seen: number;
+    dead: number;
+    not_needed: number;
+    steals: number;
+}
+export interface StatsSnapshot {
+    downloaded_and_checked_bytes: number;
+    fetched_bytes: number;
+    uploaded_bytes: number;
+    downloaded_and_checked_pieces: number;
+    total_piece_download_ms: number;
+    peer_stats: AggregatePeerStats;
+}
+/**
+ * Only present while the torrent is live
+ */
+export interface LiveStats {
+    snapshot: StatsSnapshot;
+    average_piece_download_time: Duration | null;
+    download_speed: Speed;
+    upload_speed: Speed;
+    time_remaining: DurationWithHumanReadable | null;
+}
+/**
+ * A torrent paused while initializing stays `initializing` with `initializing_paused: true` until it is started.
+ * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/torrent_state/stats.rs}
+ */
+export type TorrentStatsState = 'initializing' | 'live' | 'paused' | 'error';
+/**
+ * Response from `GET /torrents/{id}/stats/v1`
+ */
+export interface TorrentStats {
+    state: TorrentStatsState;
+    /**
+     * Only present when state is `initializing`
+     */
+    initializing_paused?: boolean;
+    /**
+     * Bytes downloaded per file, in file order
+     */
+    file_progress: number[];
+    error: string | null;
+    progress_bytes: number;
+    uploaded_bytes: number;
+    /**
+     * Total bytes of the selected files
+     */
+    total_bytes: number;
+    finished: boolean;
+    live: LiveStats | null;
+}
+export interface TorrentFileAttributes {
+    symlink: boolean;
+    hidden: boolean;
+    padding: boolean;
+    executable: boolean;
+}
+export interface TorrentFile {
+    name: string;
+    components: string[];
+    length: number;
+    /**
+     * Whether the file is selected for download
+     */
+    included: boolean;
+    attributes: TorrentFileAttributes;
+}
+/**
+ * Response from `GET /torrents/{id}`
+ */
+export interface TorrentDetails {
+    id: number;
+    info_hash: string;
+    /**
+     * null until metadata is resolved
+     */
+    name: string | null;
+    output_folder: string;
+    total_pieces: number;
+    files: TorrentFile[];
+}
+/**
+ * Item from `GET /torrents`
+ */
+export interface TorrentListItem {
+    id: number;
+    info_hash: string;
+    name: string | null;
+    output_folder: string;
+    total_pieces: number;
+    /**
+     * Only present when listing with stats
+     */
+    stats?: TorrentStats;
+}
+export interface TorrentWithStats extends TorrentListItem {
+    stats: TorrentStats;
+}
+/**
+ * Response from `GET /torrents`
+ */
+export interface ListTorrentsResponse<T extends TorrentListItem = TorrentListItem> {
+    torrents: T[];
+}
+/**
+ * Response from `POST /torrents`
+ */
+export interface AddTorrentResponse {
+    /**
+     * null when added with `list_only`
+     */
+    id: number | null;
+    details: TorrentDetails;
+    output_folder: string;
+    seen_peers: string[] | null;
+}
+/**
+ * Query options for `POST /torrents`
+ * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api_types.rs}
+ */
+export interface AddTorrentOptions {
+    /**
+     * Allow writing over existing files on disk, rqbit refuses to add a torrent whose files already exist without this.
+     * default: true
+     */
+    overwrite: boolean;
+    /**
+     * Absolute folder to download into, defaults to the folder rqbit was started with
+     */
+    output_folder: string;
+    /**
+     * Folder inside the output folder to download into
+     */
+    sub_folder: string;
+    /**
+     * Only download files matching this regex
+     */
+    only_files_regex: string;
+    /**
+     * Only download these file indexes
+     */
+    only_files: number[];
+    /**
+     * Resolve the torrent and return its details without adding it
+     */
+    list_only: boolean;
+    /**
+     * Extra peers to connect to, ex - `['1.2.3.4:6881']`
+     */
+    initial_peers: string[];
+    /**
+     * Seconds
+     */
+    peer_connect_timeout: number;
+    /**
+     * Seconds
+     */
+    peer_read_write_timeout: number;
+    /**
+     * How long rqbit will wait to resolve magnet metadata before giving up, also used as the request timeout.
+     * default: {@link RqbitConfig.addTimeout}
+     */
+    timeout_ms: number;
+}
+export interface PeerCounters {
+    incoming_connections: number;
+    fetched_bytes: number;
+    uploaded_bytes: number;
+    total_time_connecting_ms: number;
+    connection_attempts: number;
+    connections: number;
+    errors: number;
+    fetched_chunks: number;
+    downloaded_and_checked_pieces: number;
+    total_piece_download_ms: number;
+    times_stolen_from_me: number;
+    times_i_stole: number;
+}
+export type PeerState = 'queued' | 'connecting' | 'live' | 'dead' | 'not_needed';
+export interface PeerStats {
+    counters: PeerCounters;
+    state: PeerState;
+    conn_kind: 'tcp' | 'utp' | 'socks' | null;
+    client_name: string | null;
+}
+/**
+ * Response from `GET /torrents/{id}/peer_stats`
+ */
+export interface PeerStatsResponse {
+    /**
+     * Keyed by `ip:port`
+     */
+    peers: Record<string, PeerStats>;
+}
+export interface ConnectionStatSingle {
+    attempts: number;
+    successes: number;
+    errors: number;
+}
+export interface ConnectionStatsPerFamily {
+    v4: ConnectionStatSingle;
+    v6: ConnectionStatSingle;
+}
+/**
+ * Response from `GET /stats`
+ */
+export interface SessionStats {
+    counters: {
+        fetched_bytes: number;
+        uploaded_bytes: number;
+        blocked_incoming: number;
+        blocked_outgoing: number;
+    };
+    download_speed: Speed;
+    upload_speed: Speed;
+    peers: AggregatePeerStats;
+    uptime_seconds: number;
+    connections: {
+        tcp: ConnectionStatsPerFamily;
+        utp: ConnectionStatsPerFamily;
+        socks: ConnectionStatsPerFamily;
+    };
+}
+/**
+ * Session wide rate limits, null is unlimited
+ */
+export interface RateLimits {
+    /**
+     * bytes per second
+     */
+    upload_bps: number | null;
+    /**
+     * bytes per second
+     */
+    download_bps: number | null;
+}
+/**
+ * JSON error body returned by rqbit
+ */
+export interface RqbitErrorResponse {
+    /**
+     * ex - `torrent_not_found`, `internal_error`
+     */
+    error_kind: string;
+    human_readable: string;
+    status: number;
+    status_text: string;
+    id?: string;
+}
+/**
+ * Empty response from actions like pause, start, forget and delete
+ */
+export type EmptyResponse = Record<string, never>;
+/**
+ * Response from `GET /dht/stats`
+ */
+export interface DhtStats {
+    /**
+     * This node's DHT id
+     */
+    id: string;
+    outstanding_requests: number;
+    routing_table_size: number;
+    routing_table_size_v6: number;
+}
+/**
+ * Query options for `POST /torrents/create`
+ * {@link https://github.com/ikatson/rqbit/blob/v9.0.1/crates/librqbit/src/http_api/handlers/torrents.rs}
+ */
+export interface CreateTorrentOptions {
+    /**
+     * Torrent name, defaults to the folder name
+     */
+    name: string;
+    /**
+     * Announce urls
+     */
+    trackers: string[];
+}
+export interface CreateTorrentResponse {
+    magnet: string;
+    info_hash: string;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@ctrl/rqbit",
+  "version": "0.0.1",
+  "description": "TypeScript api wrapper for rqbit using ofetch",
+  "keywords": [
+    "rqbit",
+    "torrent",
+    "typescript"
+  ],
+  "homepage": "https://rqbit.ep.workers.dev",
+  "license": "MIT",
+  "author": "Scott Cooper <scttcper@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scttcper/rqbit.git"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "lint": "oxlint . && oxfmt --check",
+    "lint:fix": "oxlint . --fix && oxfmt",
+    "prepare": "pnpm run build",
+    "build": "tsc",
+    "build:docs": "node --import ./typedoc.mjs ./node_modules/typedoc/bin/typedoc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@ctrl/shared-torrent": "^6.5.2",
+    "ofetch": "^1.5.1",
+    "type-fest": "^5.10.0",
+    "ufo": "^1.6.4",
+    "uint8array-extras": "^1.6.0"
+  },
+  "devDependencies": {
+    "@ctrl/oxlint-config": "1.5.0",
+    "@sindresorhus/tsconfig": "8.1.0",
+    "@types/node": "26.6.4",
+    "oxfmt": "0.71.0",
+    "oxlint": "1.86.0",
+    "p-wait-for": "6.0.0",
+    "typedoc": "0.28.20",
+    "typescript": "7.0.2",
+    "typescript6": "npm:typescript@6.0.3",
+    "vitest": "5.0.3"
+  },
+  "release": {
+    "branches": [
+      "master"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@12.9.1"
+}