From 002079f8a6c23ab6a6f20972191f2a1e209f5800 Mon Sep 17 00:00:00 2001
From: Tim Diekmann <tim.diekmann@3dvision.de>
Date: Sun, 30 Jun 2019 19:38:07 +0200
Subject: [PATCH] Update documentation about commands

---
 app/chat/message.py                | 36 ++++++++++++++++++++++++++++++
 app/static/js/plugins.js           |  4 ++--
 app/static/plugins/send-message.js |  2 +-
 docs/slurk_about.rst               |  6 ++---
 docs/slurk_bots.rst                | 12 ++++++++++
 5 files changed, 53 insertions(+), 7 deletions(-)

diff --git a/app/chat/message.py b/app/chat/message.py
index b7d2356b..3630f46e 100644
--- a/app/chat/message.py
+++ b/app/chat/message.py
@@ -84,6 +84,42 @@ def message_text(payload):
     return True
 
 
+@socketio.on('message_command')
+@login_required
+def message_command(payload):
+    current_user_id = current_user.get_id()
+    if not current_user_id:
+        return False, "invalid session id"
+    if not current_user.token.permissions.message_command:
+        return False, "insufficient rights"
+    if 'command' not in payload:
+        return False, 'missing argument: "msg"'
+    if 'room' not in payload:
+        return False, 'missing argument: "room"'
+
+    broadcast = payload.get('broadcast', False)
+    if broadcast and not current_user.token.permissions.message_broadcast:
+        return False, "insufficient rights"
+
+    room = Room.query.get(payload['room'])
+    if not room:
+        return False, 'Room not found'
+
+    user = {
+        'id': current_user_id,
+        'name': current_user.name,
+    }
+    emit('command', {
+        'command': payload['command'],
+        'user': user,
+        'timestamp': timegm(datetime.now().utctimetuple()),
+    }, room=room.name, broadcast=broadcast)
+    log_event("command", current_user, room, data={'command': payload['command']})
+    for room in current_user.rooms:
+        emit('stop_typing', {'user': user}, room=room.name)
+    return True
+
+
 @socketio.on('image')
 @login_required
 def message_image(payload):
diff --git a/app/static/js/plugins.js b/app/static/js/plugins.js
index 8f8530b3..65a31f2b 100644
--- a/app/static/js/plugins.js
+++ b/app/static/js/plugins.js
@@ -157,8 +157,8 @@ function submit_private_image(receiver, url, width, height, resolve, reject) {
     });
 }
 
-function submit_command(parameter, resolve, reject) {
-    socket.emit('command', { room: self_room, data: parameter }, (success, error) => {
+function submit_command(command, resolve, reject) {
+    socket.emit('message_command', { room: self_room, command: command }, (success, error) => {
         if (verify_query(success, error)) {
             if (resolve !== undefined)
                 resolve();
diff --git a/app/static/plugins/send-message.js b/app/static/plugins/send-message.js
index 4095fc5e..9860b41a 100644
--- a/app/static/plugins/send-message.js
+++ b/app/static/plugins/send-message.js
@@ -1,5 +1,5 @@
 if (text.match("^/")) {
-    submit_command(text.substr(1).split(' '));
+    submit_command(text.substr(1));
     display_message(current_user, current_timestamp, text.substr(1), true);
 } else if (text.match("^image:")) {
     submit_image(text.substr(6), 300, 300, () => {
diff --git a/docs/slurk_about.rst b/docs/slurk_about.rst
index 7b2876ef..a61fee7c 100644
--- a/docs/slurk_about.rst
+++ b/docs/slurk_about.rst
@@ -44,10 +44,8 @@ Technical concepts
   events. For instance, they can be used to create rooms, connect or disconnect clients or generate tokens for logging
   in.
 
-  **Commands** are a special kind of interaction with the server: Registered via the API, they can be used by human
-  users to control the bot, which in turn communicates with the server. Depending on the layout, commands are usually
-  prefixed with a slash as, for instance, in `/new_image_public`. In this example, the command triggers a change of what
-  is shown in the display area, visible to all clients in the current room.
+  **Commands** is basically the same as a public text message, but is only send to the users with the required
+  permissions.
 
   **Tokens**: To provide control over who is allowed to log into the chat (since we're not interested in running a
   public server here), access is regulated via tokens. Tokens need to be created in advance and link a user (who is
diff --git a/docs/slurk_bots.rst b/docs/slurk_bots.rst
index be3fae92..c916a9ed 100644
--- a/docs/slurk_bots.rst
+++ b/docs/slurk_bots.rst
@@ -184,3 +184,15 @@ If you want to change an image for example, you may use something like this:
      'attribute': "src",
      'value': url)
    })
+
+
+Commands
+~~~~~~~~
+
+Commands are very similar to text message, but requires a dedicated permission. Commands are sent to a room and a bot
+can listen to a command with ``on_command``:
+
+.. code-block:: python
+
+    def on_command(self, data):
+        do_something(data)