Polls
=====

Moderators can create polls, which are visible while they are "open" or
"closed" and only visible to moderators while they are in "draft" or "archived"
state.

Posting polls can be locked per room to only allow polls at a certain time.  To
clear polls after or before a logical session, single polls can be deleted or
archived ("delete all" to be implemented by the client)::

    {
	id: uuid,
	room_id: uuid,
	timestamp: Datetime,
	content: String,
	state: String, // 'open', 'closed', 'draft', 'archived'
        poll_type: String, // 'choice', 'multi'
        results: Object,  // only included for mods, for closed polls, or polls the user has voted on
        answers: Array,  // ONLY INCLUDED ON "poll.list"
        is_pinned: Boolean,
        options: [
            {
                id: uuid,
                content: String,
                order: Integer,
            }
        ]
        answered: List // answers the current user has posted, available on list actions
    }

Permissions
-----------

There are three permissions involved with the polls API:

- ``room:poll.read`` to be able to see polls at all
- ``room:poll.vote`` to be able to vote on polls
- ``room:poll.manage`` to be able to update or delete polls, and to activate and deactivate the polls module

Room Config
-----------

To enable polls for a room, add the polls module to the room modules::

    {
        "name": "Room with polls",
        "modules": [{
            type: 'poll',
            config: {
                active: true,  // false by default
                requires_moderation: false  // true by default
            }
        }],
        …
    }

## ``poll.create``

To create a poll, send a message like this::

    => ["poll.create", 1234, {"room": "room_0", "content": "What is your favourite colour?", options=[{"content": "Yes", "order": 1}, {"content": "No", "order": 2}]}]
    <- ["success", 1234, {"poll": {…}}]
    <= ["poll.created_or_updated", {"poll": {…}}]

On creates and on updates, all people in the room who have the required access rights will receive a message like this::

    <= ["poll.created_or_updated", {"poll": {…}}]

## ``poll.update``

To update a poll (only permitted for moderators), send a message like this::

    => ["poll.update", 1234, {"room": 123, "id": "UUID", "state": "visible"}]
    <- ["success", 1234, {"poll": {…}}]
    <= ["poll.created_or_updated", {"poll": {…}}]

To change the options, adjust the ``"options"``. To update an option, remember
to include its ID, to remove it, drop it from the options list, and to add a
new option, add it to the list without an ID.

## ``poll.list``

Given a room ID, return all the polls that are visible to the user::

    => ["poll.list", 1234, {"room": "room_0"}]
    <- ["success", 1234, [{"id": }, ...]

Note that the poll object has an added ``answers``  # TODO wtf is in there?
boolean attribute denoting how the user has answered this poll.

## ``poll.vote``

Given a room ID and a poll ID, users can select one or multiple options as a list of IDs::

    => ["poll.vote", 1234, {"room": "room_0", "id": 12, "options": ["ed1", "ed2"]}]
    <- ["success", 1234, [{"id": }, ...]

## ``poll.delete``

Only moderators may delete polls. Delete notifications are broadcasted like this::

    => ["poll.delete", 1234, {"room": "room_0", "id": 12}]
    <- ["success", 1234, [{"id": }, ...]
    <= ["poll.deleted", {"room": "room_0", "id": 12}]

## ``poll.pin``, ``poll.unpin``

Only moderators may pin polls, like this::

    => ["poll.pin", 1234, {"room": "room_0", "id": 12}]
    <- ["success", 1234, [{"id": }, ...]
    <= ["poll.pinned", {"room": "room_0", "id": 12}]

Unpinning does not require an ID::

    => ["poll.unpin", 1234, {"room": "room_0"}]
    <- ["success", 1234, [{}, ...]
    <= ["poll.unpinned", {"room": "room_0"}]