moved plugin documentation to plugins folder

doc/PLUGINS.md

@@ -1,99 +0,0 @@
-Plugins allow to dynamically register custom endpoints without forking this project.
-
-# Why?
-
-Imagine that you want to use the Signal REST API in a software component that has some restrictions regarding the payload it supports. To give you a real world example: If you want to use the Signal REST API to send Signal notifications from your Synology NAS to your phone, the HTTP endpoint must have only "flat" parameters - i.e array parameters in the JSON payload aren't allowed. Since the `recipients` parameter in the `/v2/send` endpoint is a array parameter, the send endpoint cannot be used in the Synology NAS. In order to work around that limitation, you can write a small custom plugin in Lua, to create a custom send endpoint, which exposes a single `recipient` string instead of an array.
-
-# How to write a custom plugin
-
-In order to use plugins, you first need to enable that feature. This can be done by setting the environment variable `ENABLE_PLUGINS` to `true` in the `docker-compose.yml` file.
-
-e.g:
-
-```
-services:                                                                                                                                                                                                        
-  signal-cli-rest-api:
-    image: bbernhard/signal-cli-rest-api:latest
-    environment:
-      - MODE=json-rpc #supported modes: json-rpc, native, normal
-      - ENABLE_PLUGINS=true #enable plugins
-``` 
-
-A valid plugin consists of a definition file (with the file ending `.def`) and a matching lua script file (with the file ending `.lua`). Both of those files must have the same filename and are placed in a folder called `plugins` on the host filesystem. Now, bind mount the `plugins` folder from your host system into the `/plugins` folder inside the docker container. This can be done in the `docker-compose.yml` file:
-
-```
-services:
-  signal-cli-rest-api:
-    image: bbernhard/signal-cli-rest-api:latest
-  environment:
-    - MODE=json-rpc #supported modes: json-rpc, native, normal
-    - ENABLE_PLUGINS=true
-  volumes:
-    - "./signal-cli-config:/home/.local/share/signal-cli" 
-    - "./plugins:/plugins" #map "plugins" folder on host system into docker container.
-```
-
-# The definition file
-
-The definition file (with the file suffix `.def`) contains some metadata which is necessary to properly register the new endpoint. A proper definition file looks like this:
-
-```
-endpoint: my-custom-send-endpoint/:number 
-method: POST
-```
-
-The `endpoint` specifies the URI of the newly created endpoint. All custom endpoints are registered under the `/v1/plugins` endpoint. So, our `my-custom-send-endpoint` will be available at `/v1/plugins/my-custom-endpoint`. If you want to use variables inside the endpoint, prefix them with a `:`.
-
-The `method` parameter specifies the HTTP method that is used for the endpoint registration.
-
-# The script file
-
-The script file (with the file suffix `.lua`) contains the implementation of the endpoint.
-
-Example:
-
-```
-local http = require("http")
-local json = require("json")
-
-local url = "http://127.0.0.1:8080/v2/send"
-
-local customEndpointPayload = json.decode(pluginInputData.payload)
-
-local sendEndpointPayload = {
-    recipients = {customEndpointPayload.recipient},
-    message = customEndpointPayload.message,
-    number = pluginInputData.Params.number
-}
-
-local encodedSendEndpointPayload = json.encode(sendEndpointPayload)
-
-response, error_message = http.request("POST", url, {
-    timeout="30s",
-    headers={
-        Accept="*/*",
-        ["Content-Type"]="application/json"
-    },
-    body=encodedSendEndpointPayload
-})
-
-pluginOutputData:SetPayload(response["body"])
-pluginOutputData:SetHttpStatusCode(response.status_code)
-```
-
-What the lua script does, is parse the JSON payload from the custom request, extract the `recipient` and the `message` from the payload and the `number` from the URL parameter and call the `/v2/send` endpoint with those parameters. The HTTP status code and the body that is returned by the HTTP request is then returned to the caller (this is done via the `pluginOutputData:SetPayload` and `pluginOutputData:SetHttpStatusCode` functions.
-
-If you now invoke the following curl command, a message gets sent:
-
-`curl -X POST -H "Content-Type: application/json" -d '{"message": "test", "recipient": "<recipient>"}' 'http://127.0.0.1:8080/v1/plugins/my-custom-send-endpoint/<registered signal number>'`
-
-# Pass commands from/to the lua script
-
-When a new plugin is registered, some parameters are automatically passed as global variables to the lua script:
-
-* `pluginInputData.payload`: the (JSON) payload that is passed to the custom endpoint
-* `pluginInputData.Params`: a map of all parameters that are part of the URL, which were defined in the definition file (i.e those parameters that were defined with `:` prefixed in the URL)
-
-In order to return values from the lua script, the following functions are available:
-* `pluginOutputData:SetPayload()`: Set the (JSON) payload that is returned to the caller
-* `pluginOutputData:SetHttpStatusCode()`: Set the HTTP status code that is returned to the caller