From 1aec083e968edd93b52dbe59b64d101940115cee Mon Sep 17 00:00:00 2001
From: Andrey Borysenko <andrey18106x@gmail.com>
Date: Wed, 9 Aug 2023 19:02:09 +0300
Subject: [PATCH] FileActionsMenu docs draft (#31)

---
 docs/api/fileactionsmenu.rst                  | 108 ++++++++++++++++++
 docs/api/index.rst                            |   2 +
 docs/definitions.rst                          |   1 +
 lib/Migration/Version1000Date202305221555.php |   1 -
 4 files changed, 111 insertions(+), 1 deletion(-)
 create mode 100644 docs/api/fileactionsmenu.rst

diff --git a/docs/api/fileactionsmenu.rst b/docs/api/fileactionsmenu.rst
new file mode 100644
index 00000000..5b57b314
--- /dev/null
+++ b/docs/api/fileactionsmenu.rst
@@ -0,0 +1,108 @@
+=================
+File Actions Menu
+=================
+
+FileActionsMenu is a simple API for registering entry to the file actions menu for ExApps.
+AppEcosystemV2 takes responsibility to register FileActionsMenu, ExApps needs only to register it in AppEcosystemV2.
+
+.. note::
+
+	FileActionsMenu rendered only for enabled ExApps.
+
+Register
+^^^^^^^^
+
+OCS endpoint: ``POST /apps/app_ecosystem_v2/api/v1/files/actions/menu``
+
+Params
+******
+
+.. code-block:: json
+
+	{
+		"name": "unique_name_of_file_actions_menu",
+		"display_name": "Display name (for UI listing)",
+		"mime": "mime of files where to display action menu",
+		"permissions": "permissions",
+		"order": "order_in_file_actions_menu",
+		"icon": "url_to_icon",
+		"icon_class": "icon-class (alternative way of setting icon)",
+		"action_handler": "/action_handler_route (on ExApp)"
+	}
+
+
+Unregister
+^^^^^^^^^^
+
+OCS endpoint: ``DELETE /apps/app_ecosystem_v2/api/v1/files/actions/menu``
+
+Params
+******
+
+
+.. code-block:: json
+
+	{
+		"fileActionMenuName": "unique_name_of_file_action_menu"
+	}
+
+Action payload to ExApp
+^^^^^^^^^^^^^^^^^^^^^^^
+
+When FileActionsMenu invoked, AppEcosystemV2 forwards action for handling to ExApp.
+The following data is sent to ExApp FileActionsMenu handler from the context of action:
+
+.. code-block:: json
+
+	{
+		"actionName": "registered_files_actions_menu_name",
+		"actionHandler": "/file_action_menu_ex_app_handler_route",
+		"actionFile": {
+			"fileId": "123",
+			"name": "filename",
+			"directory": "/relative/to/user/path/to/directory",
+			"etag": "file_etag",
+			"mime": "file_full_mime",
+			"favorite": "nc_favorite_flag",
+			"permissions": "file_permissions_for_owner",
+		}
+	}
+
+
+Request flow
+^^^^^^^^^^^^
+
+General workflow of ExApp based on FileActionsMenu.
+
+User action
+***********
+
+.. mermaid::
+
+	sequenceDiagram
+		User->>FileActionMenu: Press on registered ExApp action
+		FileActionMenu->>AppEcosystemV2: send action context payload
+		AppEcosystemV2->>ExApp: forward request to handler
+		ExApp->>AppEcosystemV2: handler accepted action status
+		AppEcosystemV2->>User: Alert (action sent or error)
+
+
+Action results
+**************
+
+File processing results could be stored next to initial file or anywhere else,
+e.g. on configured location in ExApp settings (``appconfig_ex``) or ExApp user settings (``preferences_ex``).
+
+.. mermaid::
+
+	sequenceDiagram
+		ExApp->>Nextcloud: Upload result file
+		ExApp->>AppEcosystemV2: Send notification about action results
+
+Examples
+^^^^^^^^
+
+Here is a list of simple example ExApps based on FileActionsMenu:
+
+* `video_to_gif <https://github.com/cloud-py-api/nc_py_api/tree/main/examples/as_app/to_gif>`_ - ExApp based on FileActionsMenu to convert videos to gif in place
+* `upscaler_demo <https://github.com/cloud-py-api/upscaler_demo.git>`_ - ExApp based on FileActionsMenu to upscale image in place
diff --git a/docs/api/index.rst b/docs/api/index.rst
index a8c78b38..450c60b9 100644
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -4,5 +4,7 @@ AppEcosystemV2 APIs
 
 
 .. toctree::
+	:maxdepth: 2
 
+	fileactionsmenu
 	notifications
diff --git a/docs/definitions.rst b/docs/definitions.rst
index f89a4fc5..2cad8ecd 100644
--- a/docs/definitions.rst
+++ b/docs/definitions.rst
@@ -12,3 +12,4 @@ AppEcosystemV2 brings out the following terms frequently used in the code:
 * ``AppEcosystemAuth`` - AppEcosystemV2 authentication
 * ``ExAppScope`` - granted to ExApp scope group of access to API routes
 * ``ExAppApiScope`` - pre-defined scope group of access to list of API routes
+* ``FileActionsMenu`` - entry in files actions menu (context menu)
diff --git a/lib/Migration/Version1000Date202305221555.php b/lib/Migration/Version1000Date202305221555.php
index 167c73a2..a7ddc5f9 100644
--- a/lib/Migration/Version1000Date202305221555.php
+++ b/lib/Migration/Version1000Date202305221555.php
@@ -198,7 +198,6 @@ public function changeSchema(IOutput $output, Closure $schemaClosure, array $opt
 				'notnull' => true,
 				'default' => 'file',
 			]);
-			// https://nextcloud.github.io/nextcloud-files/enums/Permission.html
 			$table->addColumn('permissions', Types::STRING, [
 				'notnull' => true,
 			]);