@remote-app/transmission-client 0.1.4 → 0.23.0

package/README.md

@@ -2,60 +2,103 @@
 
 ![npm](https://img.shields.io/npm/v/@remote-app/transmission-client)
 
-A lightweight Transmission RPC client.
+A lightweight [Transmission](https://transmissionbt.com/) RPC client for Node.js and React Native.
 
 ## Install
 
 ```bash
-$ npm install @remote-app/transmission-client
+npm install @remote-app/transmission-client
 ```
 
-## Supported methods
+## Usage
+
+```typescript
+import TransmissionClient from "@remote-app/transmission-client";
+
+const client = new TransmissionClient({
+  url: "http://localhost:9091/transmission/rpc",
+  username: "admin",
+  password: "admin",
+});
+
+// Get all torrents
+const response = await client.request({
+  method: "torrent-get",
+  arguments: {
+    fields: ["id", "name", "status", "percentDone", "rateDownload"],
+  },
+});
+
+console.log(response.arguments.torrents);
+
+// Add a torrent
+await client.request({
+  method: "torrent-add",
+  arguments: { filename: "magnet:?xt=urn:btih:..." },
+});
+
+// Update session settings
+await client.request({
+  method: "session-set",
+  arguments: { "alt-speed-down": 500 },
+});
+```
+
+The client handles Transmission's CSRF protection automatically (409 session-id negotiation).
+
+## API
+
+The client exposes a single typed `request` method. The `method` field determines which arguments are accepted and what the response looks like.
 
 ### Torrent methods
-- Torrent actions
-  - [x] torrent-start
-  - [x] torrent-start-now
-  - [x] torrent-stop
-  - [x] torrent-verify
-  - [x] torrent-reannounce
-- Torrent mutator
-  - [x] torrent-set
-- Torrent accessor
-  - [x] torrent-get
-- Torrent addition
-  - [x] torrent-add
-- Torrent removal
-  - [x] torrent-remove
-- Move torrent
-  - [x] torrent-set-location
-- Renaming torrent
-  - [ ] torrent-rename-path
+
+- `torrent-start` / `torrent-start-now` / `torrent-stop`
+- `torrent-verify` / `torrent-reannounce`
+- `torrent-set` / `torrent-get`
+- `torrent-add` / `torrent-remove`
+- `torrent-set-location` / `torrent-rename-path`
 
 ### Session methods
-- Session accessor
-  - [x] session-get
-- Session mutator
-   - [x] session-set
-- Session statistics
-  - [x] session-stats
-- Session shutdown
-  - [ ] session-close
-
-### Blocklist
-- Mutator
-  - [ ] blocklist-update
-
-### Port
-- Check
-  - [ ] port-test
-
-### Space
-- Check
-  - [x] free-space
-
-### Groups
-- Group accessor
-  - [ ] group-get
-- Group mutator
-  - [ ] group-set
+
+- `session-get` / `session-set`
+- `session-stats` / `session-close`
+
+### Queue methods
+
+- `queue-move-top` / `queue-move-up` / `queue-move-down` / `queue-move-bottom`
+
+### Other
+
+- `blocklist-update`
+- `port-test`
+- `free-space`
+- `group-get` / `group-set`
+
+## Error handling
+
+```typescript
+import TransmissionClient, {
+  HTTPError,
+  TransmissionError,
+  ResponseParseError,
+} from "@remote-app/transmission-client";
+
+try {
+  await client.request({ method: "session-stats" });
+} catch (error) {
+  if (error instanceof HTTPError) {
+    // Non-200 HTTP response (e.g. 401 Unauthorized)
+    console.error(error.status, error.message);
+  } else if (error instanceof TransmissionError) {
+    // Transmission returned result !== "success"
+    console.error(error.message);
+  } else if (error instanceof ResponseParseError) {
+    // Response body was not valid JSON
+    console.error(error.status, error.body);
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,111 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+const require_torrent_get = require('./torrent-get-C1p73gUr.cjs');
+let base_64 = require("base-64");
+
+//#region src/error.ts
+var HTTPError = class extends Error {
+	constructor(status, message, body) {
+		super(message);
+		this.status = status;
+		this.message = message;
+		this.body = body;
+		this.name = "HTTPError";
+	}
+};
+var TransmissionError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.message = message;
+		this.name = "TransmissionError";
+	}
+};
+var ResponseParseError = class extends Error {
+	constructor(status, body) {
+		super("The server returned an unexpected response");
+		this.status = status;
+		this.body = body;
+		this.name = "ResponseParseError";
+	}
+};
+
+//#endregion
+//#region src/client.ts
+var TransmissionClient = class {
+	constructor(config) {
+		this.config = config;
+		this.session = null;
+		this.sessionPromise = null;
+	}
+	authHeader() {
+		if (!this.config.username && !this.config.password) return null;
+		return `Basic ${(0, base_64.encode)(`${this.config.username ?? ""}:${this.config.password ?? ""}`)}`;
+	}
+	async ensureSession() {
+		if (this.session) return;
+		if (this.sessionPromise) return await this.sessionPromise;
+		this.sessionPromise = this.fetchSession();
+		try {
+			await this.sessionPromise;
+		} finally {
+			this.sessionPromise = null;
+		}
+	}
+	async fetchSession() {
+		const headers = new Headers({ "Content-Type": "application/json" });
+		const auth = this.authHeader();
+		if (auth) headers.set("Authorization", auth);
+		const response = await fetch(new Request(this.config.url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({ method: "session-stats" })
+		}));
+		if (response.status !== 409) {
+			const body = await response.text();
+			if (!response.ok) throw new HTTPError(response.status, response.statusText, body);
+			throw new HTTPError(response.status, "Expected Transmission session negotiation response", body);
+		}
+		const nextSession = response.headers.get("x-transmission-session-id");
+		if (!nextSession) throw new HTTPError(409, "Missing x-transmission-session-id header");
+		this.session = nextSession;
+	}
+	async request(req, retry = true) {
+		await this.ensureSession();
+		const headers = new Headers({ "Content-Type": "application/json" });
+		headers.set("x-transmission-session-id", this.session);
+		const auth = this.authHeader();
+		if (auth) headers.set("Authorization", auth);
+		const request = new Request(this.config.url, {
+			method: "POST",
+			headers,
+			body: JSON.stringify(req)
+		});
+		const response = await fetch(request);
+		if (response.status === 409 && retry) {
+			this.session = null;
+			await this.ensureSession();
+			return await this.request(req, false);
+		}
+		if (!response.ok) {
+			const body = await response.text();
+			throw new HTTPError(response.status, response.statusText, body);
+		}
+		const text = await response.text();
+		let json;
+		try {
+			json = JSON.parse(text);
+		} catch {
+			throw new ResponseParseError(response.status, text);
+		}
+		if (json && json.result !== "success") throw new TransmissionError(json.result);
+		return json;
+	}
+};
+
+//#endregion
+exports.HTTPError = HTTPError;
+exports.Mode = require_torrent_get.Mode;
+exports.Priority = require_torrent_get.Priority;
+exports.ResponseParseError = ResponseParseError;
+exports.TorrentStatus = require_torrent_get.TorrentStatus;
+exports.TransmissionError = TransmissionError;
+exports.default = TransmissionClient;

package/dist/index.d.cts

@@ -0,0 +1,372 @@
+import { a as ResponseFor$1, c as TorrentStatus, i as Response$8, l as Identifiers, n as Priority, o as TorrentField, r as Request$17, s as TorrentForFields, t as Mode } from "./torrent-get-BosdT1jx.cjs";
+import { BandwidthGroup, BlocklistUpdateRequest, BlocklistUpdateResponse, FreeSpaceRequest, FreeSpaceResponse, GroupGetRequest, GroupGetResponse, GroupSetRequest, PortTestRequest, PortTestResponse, QueueMoveBottomRequest, QueueMoveDownRequest, QueueMoveTopRequest, QueueMoveUpRequest, SessionCloseRequest, SessionGetRequest, SessionGetResponse, SessionSetRequest, SessionStatsResponse, Torrent, TorrentAddRequest, TorrentAddResponse, TorrentGetRequest, TorrentGetResponse, TorrentReannounceRequest, TorrentRemoveRequest, TorrentRenamePathRequest, TorrentRenamePathResponse, TorrentSetLocationRequest, TorrentSetRequest, TorrentStartNowRequest, TorrentStartRequest, TorrentStopRequest, TorrentVerifyRequest } from "./schemas.cjs";
+
+//#region src/rpc-calls/session-get.d.ts
+type Units = {
+  "speed-units": string[];
+  "speed-bytes": number;
+  "size-units": string[];
+  "size-bytes": number;
+  "memory-units": string[];
+  "memory-bytes": number;
+};
+type Response$7 = {
+  "alt-speed-down"?: number;
+  "alt-speed-enabled"?: boolean;
+  "alt-speed-time-begin"?: number;
+  "alt-speed-time-enabled"?: boolean;
+  "alt-speed-time-end"?: number;
+  "alt-speed-time-day"?: number;
+  "alt-speed-up"?: number;
+  "blocklist-url"?: string;
+  "blocklist-enabled"?: boolean;
+  "blocklist-size"?: number;
+  "cache-size-mb"?: number;
+  "config-dir"?: string;
+  "default-trackers"?: string;
+  "dht-enabled"?: boolean;
+  "download-dir"?: string;
+  "download-dir-free-space"?: number;
+  "download-queue-size"?: number;
+  "download-queue-enabled"?: boolean;
+  encryption?: string;
+  "idle-seeding-limit"?: number;
+  "idle-seeding-limit-enabled"?: boolean;
+  "incomplete-dir"?: string;
+  "incomplete-dir-enabled"?: boolean;
+  "lpd-enabled"?: boolean;
+  "peer-limit-global"?: number;
+  "peer-limit-per-torrent"?: number;
+  "pex-enabled"?: boolean;
+  "peer-port"?: number;
+  "peer-port-random-on-start"?: boolean;
+  "port-forwarding-enabled"?: boolean;
+  "queue-stalled-enabled"?: boolean;
+  "queue-stalled-minutes"?: number;
+  "rename-partial-files"?: boolean;
+  reqq?: number;
+  "rpc-version"?: number;
+  "rpc-version-minimum"?: number;
+  "rpc-version-semver"?: string;
+  "script-torrent-added-enabled"?: boolean;
+  "script-torrent-added-filename"?: string;
+  "script-torrent-done-filename"?: string;
+  "script-torrent-done-enabled"?: boolean;
+  "script-torrent-done-seeding-enabled"?: boolean;
+  "script-torrent-done-seeding-filename"?: string;
+  seedRatioLimit?: number;
+  seedRatioLimited?: boolean;
+  "seed-queue-size"?: number;
+  "seed-queue-enabled"?: boolean;
+  "sequential-download"?: boolean;
+  "session-id"?: string;
+  "speed-limit-down"?: number;
+  "speed-limit-down-enabled"?: boolean;
+  "speed-limit-up"?: number;
+  "speed-limit-up-enabled"?: boolean;
+  "start-added-torrents"?: boolean;
+  "trash-original-torrent-files"?: boolean;
+  units?: Units;
+  "utp-enabled"?: boolean;
+  version?: string;
+};
+type SessionGetField = keyof Response$7;
+type SelectedSessionFields<F extends readonly SessionGetField[]> = { [K in F[number]]-?: NonNullable<Response$7[K]> };
+type IsTuple<T extends readonly unknown[]> = number extends T["length"] ? false : true;
+type SessionGetForFields<F extends readonly SessionGetField[]> = IsTuple<F> extends true ? SelectedSessionFields<F> : Response$7;
+type ResponseFor<F extends readonly SessionGetField[]> = SessionGetForFields<F>;
+type Request$16<F extends readonly SessionGetField[] = readonly SessionGetField[]> = {
+  fields?: F;
+};
+//#endregion
+//#region src/rpc-calls/session-set.d.ts
+type Request$15 = Partial<Response$7>;
+//#endregion
+//#region src/rpc-calls/session-stats.d.ts
+type CurrentStats = {
+  uploadedBytes: number;
+  downloadedBytes: number;
+  filesAdded: number;
+  sessionCount: number;
+  secondsActive: number;
+};
+type CumulativeStats = {
+  uploadedBytes: number;
+  downloadedBytes: number;
+  filesAdded: number;
+  sessionCount: number;
+  secondsActive: number;
+};
+type Response$6 = {
+  activeTorrentCount: number;
+  downloadSpeed: number;
+  pausedTorrentCount: number;
+  torrentCount: number;
+  uploadSpeed: number;
+  "cumulative-stats": CumulativeStats;
+  "current-stats": CurrentStats;
+};
+//#endregion
+//#region src/rpc-calls/session-close.d.ts
+type Request$14 = never;
+//#endregion
+//#region src/rpc-calls/free-space.d.ts
+type Response$5 = {
+  path: string;
+  "size-bytes": number;
+};
+type Request$13 = {
+  path: string;
+};
+//#endregion
+//#region src/rpc-calls/torrent-set.d.ts
+type Request$12 = Identifiers & {
+  bandwidthPriority?: Priority;
+  downloadLimit?: number;
+  downloadLimited?: boolean;
+  "files-wanted"?: number[];
+  "files-unwanted"?: number[];
+  honorsSessionLimits?: boolean;
+  labels?: string[];
+  location?: string;
+  "peer-limit"?: number;
+  "priority-high"?: number[];
+  "priority-low"?: number[];
+  "priority-normal"?: number[];
+  queuePosition?: number;
+  seedIdleLimit?: number;
+  seedIdleMode?: Mode;
+  seedRatioLimit?: number;
+  seedRatioMode?: Mode;
+  trackerAdd?: string[];
+  trackerRemove?: number[];
+  trackerReplace?: Array<{
+    id: number;
+    announce: string;
+  }>;
+  trackerList?: string;
+  group?: string;
+  sequentialDownload?: boolean;
+  uploadLimit?: number;
+  uploadLimited?: boolean;
+};
+//#endregion
+//#region src/rpc-calls/torrent-add.d.ts
+type optionals = {
+  cookies?: string;
+  "download-dir"?: string;
+  labels?: string[];
+  paused?: boolean;
+  "peer-limit"?: number;
+  bandwidthPriority?: number;
+  "files-wanted"?: number[];
+  "files-unwanted"?: number[];
+  "priority-high"?: number[];
+  "priority-low"?: number[];
+  "priority-normal"?: number[];
+  "sequential-download"?: boolean;
+};
+type Request$11 = ({
+  filename: string;
+} | {
+  metainfo: string;
+}) & optionals;
+type Response$4 = {
+  "torrent-added": Pick<Response$8["torrents"][number], "id" | "name" | "hashString">[];
+} | {
+  "torrent-duplicate": Pick<Response$8["torrents"][number], "id" | "name" | "hashString">[];
+};
+//#endregion
+//#region src/rpc-calls/torrent-remove.d.ts
+type Request$10 = Identifiers & {
+  "delete-local-data"?: boolean;
+};
+//#endregion
+//#region src/rpc-calls/torrent-set-location.d.ts
+type Request$9 = Identifiers & {
+  location: string;
+  move?: boolean;
+};
+//#endregion
+//#region src/rpc-calls/torrent-rename-path.d.ts
+type Request$8 = Identifiers & {
+  path: string;
+  name: string;
+};
+type Response$3 = {
+  path: string;
+  name: string;
+  id: number;
+};
+//#endregion
+//#region src/rpc-calls/queue-move-top.d.ts
+type Request$7 = Identifiers;
+//#endregion
+//#region src/rpc-calls/queue-move-up.d.ts
+type Request$6 = Identifiers;
+//#endregion
+//#region src/rpc-calls/queue-move-down.d.ts
+type Request$5 = Identifiers;
+//#endregion
+//#region src/rpc-calls/queue-move-bottom.d.ts
+type Request$4 = Identifiers;
+//#endregion
+//#region src/rpc-calls/blocklist-update.d.ts
+type Request$3 = never;
+type Response$2 = {
+  "blocklist-size": number;
+};
+//#endregion
+//#region src/rpc-calls/port-test.d.ts
+type Request$2 = {
+  ipProtocol?: "ipv4" | "ipv6";
+};
+type Response$1 = {
+  "port-is-open": boolean;
+  ipProtocol?: "ipv4" | "ipv6";
+};
+//#endregion
+//#region src/rpc-calls/group-get.d.ts
+type BandwidthGroup$1 = {
+  honorsSessionLimits: boolean;
+  name: string;
+  "speed-limit-down-enabled": boolean;
+  "speed-limit-down": number;
+  "speed-limit-up-enabled": boolean;
+  "speed-limit-up": number;
+};
+type Request$1 = {
+  group?: string | string[];
+};
+type Response = {
+  group: BandwidthGroup$1[];
+};
+//#endregion
+//#region src/rpc-calls/group-set.d.ts
+type Request = {
+  honorsSessionLimits?: boolean;
+  name: string;
+  "speed-limit-down-enabled"?: boolean;
+  "speed-limit-down"?: number;
+  "speed-limit-up-enabled"?: boolean;
+  "speed-limit-up"?: number;
+};
+//#endregion
+//#region src/rpc-call.d.ts
+type SessionMethods = "session-get" | "session-set" | "session-stats" | "session-close" | "free-space";
+type TorrentMethods = "torrent-start" | "torrent-start-now" | "torrent-stop" | "torrent-verify" | "torrent-reannounce" | "torrent-set" | "torrent-get" | "torrent-add" | "torrent-remove" | "torrent-set-location" | "torrent-rename-path";
+type QueueMethods = "queue-move-top" | "queue-move-up" | "queue-move-down" | "queue-move-bottom";
+type OtherMethods = "blocklist-update" | "port-test" | "group-get" | "group-set";
+type Methods = SessionMethods | TorrentMethods | QueueMethods | OtherMethods;
+type RPCRequest<M, T> = {
+  method: M;
+  arguments?: T;
+  tag?: number;
+};
+type RPCResponse<A> = {
+  result: string;
+  arguments: A;
+  tag?: number;
+};
+type MethodRequest = {
+  "session-get": Request$16;
+  "session-set": Request$15;
+  "session-stats": never;
+  "session-close": Request$14;
+  "free-space": Request$13;
+  "torrent-start": Identifiers;
+  "torrent-start-now": Identifiers;
+  "torrent-stop": Identifiers;
+  "torrent-verify": Identifiers;
+  "torrent-reannounce": Identifiers;
+  "torrent-remove": Request$10;
+  "torrent-set-location": Request$9;
+  "torrent-get": Request$17;
+  "torrent-add": Request$11;
+  "torrent-set": Request$12;
+  "torrent-rename-path": Request$8;
+  "queue-move-top": Request$7;
+  "queue-move-up": Request$6;
+  "queue-move-down": Request$5;
+  "queue-move-bottom": Request$4;
+  "blocklist-update": Request$3;
+  "port-test": Request$2;
+  "group-get": Request$1;
+  "group-set": Request;
+};
+type MethodResponse = {
+  "session-get": Response$7;
+  "session-set": void;
+  "session-stats": Response$6;
+  "session-close": void;
+  "free-space": Response$5;
+  "torrent-start": void;
+  "torrent-start-now": void;
+  "torrent-stop": void;
+  "torrent-verify": void;
+  "torrent-reannounce": void;
+  "torrent-remove": void;
+  "torrent-set-location": void;
+  "torrent-get": Response$8;
+  "torrent-add": Response$4;
+  "torrent-set": void;
+  "torrent-rename-path": Response$3;
+  "queue-move-top": void;
+  "queue-move-up": void;
+  "queue-move-down": void;
+  "queue-move-bottom": void;
+  "blocklist-update": Response$2;
+  "port-test": Response$1;
+  "group-get": Response;
+  "group-set": void;
+};
+type RequestForMethod<M extends Methods> = RPCRequest<M, MethodRequest[M]>;
+type AnyRequest = { [K in Methods]: RequestForMethod<K> }[Methods];
+type MethodResponseForRequest<M extends Methods, Req extends RequestForMethod<M>> = M extends "torrent-get" ? Req extends {
+  arguments: {
+    fields: infer F extends readonly TorrentField[];
+  };
+} ? ResponseFor$1<F> : Response$8 : M extends "session-get" ? Req extends {
+  arguments: {
+    fields: infer F extends readonly SessionGetField[];
+  };
+} ? ResponseFor<F> : Response$7 : MethodResponse[M];
+type ResponseForRequest<Req extends AnyRequest> = Req extends RequestForMethod<infer M extends Methods> ? RPCResponse<MethodResponseForRequest<M, Req>> : never;
+//#endregion
+//#region src/error.d.ts
+declare class HTTPError extends Error {
+  readonly status: number;
+  readonly message: string;
+  readonly body?: string | undefined;
+  constructor(status: number, message: string, body?: string | undefined);
+}
+declare class TransmissionError extends Error {
+  readonly message: string;
+  constructor(message: string);
+}
+declare class ResponseParseError extends Error {
+  readonly status: number;
+  readonly body: string;
+  constructor(status: number, body: string);
+}
+//#endregion
+//#region src/config.d.ts
+type TransmissionConfig = {
+  url: string;
+  username?: string;
+  password?: string;
+};
+//#endregion
+//#region src/client.d.ts
+declare class TransmissionClient {
+  private config;
+  private session;
+  private sessionPromise;
+  constructor(config: TransmissionConfig);
+  private authHeader;
+  private ensureSession;
+  private fetchSession;
+  request<Req extends AnyRequest>(req: Req, retry?: boolean): Promise<ResponseForRequest<Req>>;
+}
+//#endregion
+export { type BandwidthGroup, type BlocklistUpdateRequest, type BlocklistUpdateResponse, type FreeSpaceRequest, type FreeSpaceResponse, type GroupGetRequest, type GroupGetResponse, type GroupSetRequest, HTTPError, type Methods, Mode, type PortTestRequest, type PortTestResponse, Priority, type QueueMoveBottomRequest, type QueueMoveDownRequest, type QueueMoveTopRequest, type QueueMoveUpRequest, ResponseParseError, type SessionCloseRequest, type SessionGetField, type SessionGetForFields, type SessionGetRequest, type SessionGetResponse, type ResponseFor as SessionGetResponseFor, type SessionSetRequest, type SessionStatsResponse, type Torrent, type TorrentAddRequest, type TorrentAddResponse, type TorrentField, type TorrentForFields, type TorrentGetRequest, type TorrentGetResponse, type ResponseFor$1 as TorrentGetResponseFor, type TorrentReannounceRequest, type TorrentRemoveRequest, type TorrentRenamePathRequest, type TorrentRenamePathResponse, type TorrentSetLocationRequest, type TorrentSetRequest, type TorrentStartNowRequest, type TorrentStartRequest, TorrentStatus, type TorrentStopRequest, type TorrentVerifyRequest, TransmissionError, TransmissionClient as default };