docs: improve documentation of delete torrents API

client/src/javascript/actions/TorrentActions.ts

@@ -1,6 +1,6 @@
 import axios from 'axios';
 
-import type {AddTorrentByURLOptions, MoveTorrentsOptions} from '@shared/types/Action';
+import type {AddTorrentByURLOptions, DeleteTorrentsOptions, MoveTorrentsOptions} from '@shared/types/Action';
 import type {TorrentProperties} from '@shared/types/Torrent';
 
 import AppDispatcher from '../dispatcher/AppDispatcher';
@@ -59,9 +59,9 @@ const TorrentActions = {
         },
       ),
 
-  deleteTorrents: (hashes: Array<TorrentProperties['hash']>, deleteData: boolean) =>
+  deleteTorrents: (options: DeleteTorrentsOptions) =>
     axios
-      .post(`${baseURI}api/client/torrents/delete`, {hashes, deleteData})
+      .post(`${baseURI}api/client/torrents/delete`, options)
       .then((json) => json.data)
       .then(
         (data) => {
@@ -69,8 +69,8 @@ const TorrentActions = {
             type: 'CLIENT_REMOVE_TORRENT_SUCCESS',
             data: {
               data,
-              count: hashes.length,
-              deleteData,
+              count: options.hashes.length,
+              deleteData: options.deleteData || false,
             },
           });
         },
@@ -79,7 +79,7 @@ const TorrentActions = {
             type: 'CLIENT_REMOVE_TORRENT_ERROR',
             error: {
               error,
-              count: hashes.length,
+              count: options.hashes.length,
             },
           });
         },

client/src/javascript/components/modals/remove-torrents-modal/RemoveTorrentsModal.js

@@ -73,9 +73,10 @@ class RemoveTorrentsModal extends React.Component {
   }
 
   handleRemovalConfirmation = () => {
-    const torrents = TorrentStore.getSelectedTorrents();
-    const formData = this.formRef.getFormData();
-    TorrentActions.deleteTorrents(torrents, formData.deleteData);
+    TorrentActions.deleteTorrents({
+      hashes: TorrentStore.getSelectedTorrents(),
+      deleteData: this.formRef.getFormData().deleteData,
+    });
   };
 
   render() {

server/routes/client.ts

@@ -1,6 +1,8 @@
 import express from 'express';
 import multer from 'multer';
 
+import type {DeleteTorrentsOptions} from '@shared/types/Action';
+
 import ajaxUtil from '../util/ajaxUtil';
 import booleanCoerce from '../middleware/booleanCoerce';
 import client from '../models/client';
@@ -83,8 +85,17 @@ router.post('/torrents/move', (req, res) => {
   client.moveTorrents(req.user, req.services, req.body, ajaxUtil.getResponseFn(res));
 });
 
-router.post('/torrents/delete', (req, res) => {
-  const {deleteData, hashes} = req.body;
+/**
+ * POST /api/client/torrents/delete
+ * @summary Removes torrents from Flood. Optionally deletes data of torrents.
+ * @tags Torrents
+ * @security AuthenticatedUser
+ * @param {DeleteTorrentsOptions} request.body.required - options - application/json
+ * @return {object} 200 - success response - application/json
+ * @return {Error} 500 - failure response - application/json
+ */
+router.post<unknown, unknown, DeleteTorrentsOptions>('/torrents/delete', (req, res) => {
+  const {hashes, deleteData} = req.body;
   const callback = ajaxUtil.getResponseFn(res);
 
   req.services?.clientGatewayService

server/services/clientGatewayService.ts

@@ -2,6 +2,7 @@ import path from 'path';
 import fs from 'fs';
 
 import type {Credentials} from '@shared/types/Auth';
+import type {DeleteTorrentsOptions} from '@shared/types/Action';
 import type {TorrentProperties, Torrents} from '@shared/types/Torrent';
 import type {TransferSummary} from '@shared/types/TransferData';
 
@@ -65,7 +66,13 @@ class ClientGatewayService extends BaseService<ClientGatewayServiceEvents> {
     this.torrentListReducers.push(reducer);
   }
 
-  removeTorrents({hashes, deleteData}: {hashes: Array<string>; deleteData: boolean}) {
+  /**
+   * Removes torrents from rTorrent's session. Optionally deletes data of torrents.
+   *
+   * @param {DeleteTorrentsOptions} options - An object of options...
+   * @return {Promise} - Resolves with the processed client response or rejects with the processed client error.
+   */
+  removeTorrents({hashes, deleteData}: DeleteTorrentsOptions) {
     if (this.services == null || this.services.clientRequestManager == null) {
       return Promise.reject();
     }
@@ -74,8 +81,7 @@ class ClientGatewayService extends BaseService<ClientGatewayServiceEvents> {
       (accumulator: Array<{methodName: string; params: Array<string>}>, hash, index) => {
         let eraseFileMethodCallIndex = index;
 
-        // If we're deleting files, we grab each torrents' file list before we
-        // remove them.
+        // If we're deleting files, we grab each torrents' file list before we remove them.
         if (deleteData === true) {
           // We offset the indices of these method calls so that we know exactly
           // where to retrieve the responses in the future.

shared/types/Action.ts

@@ -1,3 +1,5 @@
+import {TorrentProperties} from './Torrent';
+
 export interface AddTorrentByURLOptions {
   urls: Array<string>;
   destination: string;
@@ -14,3 +16,10 @@ export interface MoveTorrentsOptions {
   moveFiles: boolean;
   isCheckHash: boolean;
 }
+
+export interface DeleteTorrentsOptions {
+  // An array of string representing hashes of torrents to be removed
+  hashes: Array<TorrentProperties['hash']>;
+  // Whether to delete data of torrents
+  deleteData?: boolean;
+}