Add remove folder developer API endpoint (#3489)

* add remove folder api endpoint

* update purgeFolder function comment

---------

Co-authored-by: timothycarambat <rambat1010@gmail.com>

server/endpoints/api/document/index.js

@@ -14,6 +14,7 @@ const { CollectorApi } = require("../../../utils/collectorApi");
 const fs = require("fs");
 const path = require("path");
 const { Document } = require("../../../models/documents");
+const { purgeFolder } = require("../../../utils/files/purgeDocument");
 const documentsPath =
   process.env.NODE_ENV === "development"
     ? path.resolve(__dirname, "../../../storage/documents")
@@ -847,6 +848,65 @@ function apiDocumentEndpoints(app) {
     }
   );
 
+  app.delete(
+    "/v1/document/remove-folder",
+    [validApiKey],
+    async (request, response) => {
+      /*
+      #swagger.tags = ['Documents']
+      #swagger.description = 'Remove a folder and all its contents from the documents storage directory.'
+      #swagger.requestBody = {
+        description: 'Name of the folder to remove.',
+        required: true,
+        content: {
+          "application/json": {
+            schema: {
+              type: 'object',
+              properties: {
+                name: {
+                  type: 'string',
+                  example: "my-folder"
+                }
+              }
+            }
+          }
+        }
+      }
+      #swagger.responses[200] = {
+        content: {
+          "application/json": {
+            schema: {
+              type: 'object',
+              example: {
+                success: true,
+                message: "Folder removed successfully"
+              }
+            }
+          }
+        }
+      }
+      #swagger.responses[403] = {
+        schema: {
+          "$ref": "#/definitions/InvalidAPIKey"
+        }
+      }
+      */
+      try {
+        const { name } = reqBody(request);
+        await purgeFolder(name);
+        response
+          .status(200)
+          .json({ success: true, message: "Folder removed successfully" });
+      } catch (e) {
+        console.error(e);
+        response.status(500).json({
+          success: false,
+          message: `Failed to remove folder: ${e.message}`,
+        });
+      }
+    }
+  );
+
   app.post(
     "/v1/document/move-files",
     [validApiKey],

server/swagger/openapi.json

@@ -1532,6 +1532,66 @@
         }
       }
     },
+    "/v1/document/remove-folder": {
+      "delete": {
+        "tags": [
+          "Documents"
+        ],
+        "description": "Remove a folder and all its contents from the documents storage directory.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "example": {
+                    "success": true,
+                    "message": "Folder removed successfully"
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "Forbidden",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidAPIKey"
+                }
+              },
+              "application/xml": {
+                "schema": {
+                  "$ref": "#/components/schemas/InvalidAPIKey"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Internal Server Error"
+          }
+        },
+        "requestBody": {
+          "description": "Name of the folder to remove.",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "example": "my-folder"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/document/move-files": {
       "post": {
         "tags": [

server/utils/files/purgeDocument.js

@@ -22,6 +22,14 @@ async function purgeDocument(filename = null) {
   return;
 }
 
+/**
+ * Purge a folder and all its contents. This will also remove all vector-cache files and workspace document associations
+ * for the documents within the folder.
+ * @notice This function is not recursive. It only purges the contents of the specified folder.
+ * @notice You cannot purge the `custom-documents` folder.
+ * @param {string} folderName - The name/path of the folder to purge.
+ * @returns {Promise<void>}
+ */
 async function purgeFolder(folderName = null) {
   if (!folderName) return;
   const subFolder = normalizePath(folderName);