docs: add websocket specification.

2019-11-01 09:31:58 +07:00 · 2019-11-01 09:31:58 +07:00 · 94f9b59f12
parent 81623db66a
commit 94f9b59f12
1 changed files with 348 additions and 0 deletions
--- a/WEBSOCKET.md
+++ b/WEBSOCKET.md
@ -0,0 +1,348 @@
+# Websocket Protocol Documentation
+
+## Table of contents
+
+- [Staff Endpoints](#staff-endpoints)
+    - [Server To Staff](#server-to-staff)
+        - [claimed](#claimed)
+        - [new](#new)
+        - [taken](#taken)
+    - [Staff to Server](#staff-to-server)
+        - [accept](#accept)
+        - [cancel](#cancel)
+        - [complete](#complete)
+        - [pick](#pick)
+        - [unpick](#unpick)
+- [Kiosk Endpoints](#kiosk-endpoints)
+    - [Kiosk to Server](#kiosk-to-server)
+        - [new](#new-1)
+        - [query](#query)
+- [Display Endpoints](#display-endpoints)
+    - [Server to Display](#server-to-display)
+        - [cancel](#cancel-1)
+        - [claimed](#claimed-1)
+        - [complete](#complete-1)
+        - [pick](#pick-1)
+        - [unpick](#unpick-1)
+
+## Staff Endpoints
+
+These endpoints are just going to be used between a staff member handling clients and the server.
+
+### Server to Staff
+
+#### claimed
+
+This message is sent to the staff when another staff member has already claimed a ticket.
+This message serves the function of letting staff members know when a ticket is no longer
+needing a staff member to claim it.
+
+##### example:
+
+```
+claimed {"id":0,"email":"example@example.com","name":"Example Name","staff":"StaffMember","start":"2019-10-01T04:12:19Z","end":"1970-01-01T00:00:00Z"}
+```
+
+This example message would tell the staff member that the ticket was claimed by 'StaffMember'.
+
+#### new
+
+This message is sent to the staff when a kiosk creates a new ticket.
+
+##### example:
+
+```
+new {"id":0,"email":"example@example.com","name":"Example Name","staff":"{}","start":"2019-10-01T04:12:19Z","end":"1970-01-01T00:00:00Z"}
+```
+
+This example message would tell the staff member that a client by the name of 'Example Name' has created a new ticket.
+
+#### taken
+
+This message is sent to staff members when they haven't picked an assigned table yet.
+The purpose of the message is to allow staff members know what tables are available to pick.
+
+#### example:
+
+```
+taken 0 3 5
+```
+
+This sample message would tell the staff member that table 0, 3, and 5 are already taken and are not available.
+
+### Staff to Server
+
+#### accept
+
+This message is sent from the staff member when they want to claim a ticket.
+
+##### example
+
+```
+accept 0
+```
+
+This sample message would claim a ticket with the ID of 0
+
+##### responses:
+
+###### error accept your session token was found to be invalid. please relogin
+
+This means that the internal token used to identify you was deamed incorrect or invalid. You must relog
+
+###### error accept you do not have a table chosen
+
+You must be assigned to a table before handling tickets.
+
+###### error accept ticket id does not exist
+
+The ticket with the provided id you are trying to accept does not exist.
+
+###### error accept this ticket is now claimed
+
+The ticket you are trying to claim has already been claimed by another user.
+
+###### error accept the ticket has already been completed or cancelled
+
+This means that when the ticket you are trying to accept is already claimed by someone else 
+
+###### success claimed `{id}`
+
+The staff member has successfully claimed the ticket.
+
+#### cancel
+
+This message is sent from the staff member when a client decided to cancel a ticket, or does not show up.
+
+##### example:
+
+```
+cancel 0
+```
+
+This example message would cancel the ticket with the id of 0
+
+##### responses:
+
+###### error cancel you are not assigned to any table
+
+You must be assigned to a table before handling tickets.
+
+###### error cancel ticket id does not exist
+
+The ticket with the provided id you are trying to cancel does not exist.
+
+###### error cancel you do not own this ticket
+
+The ticket you are trying to cancel must be owned by you.
+
+###### error cancel the ticket has already been completed or cancelled
+
+This means the ticket you are trying to cancel cannot be cancelled
+as it has already previously been, or has been completed.
+
+###### success cancel `{id}`
+
+The ticket was successfully cancelled with no issues.
+
+
+#### complete
+
+This message is sent from the staff member when a staff member completes a ticket
+
+##### example:
+
+```
+complete 0
+```
+
+This example message would complete the ticket with the id of 0
+
+##### responses:
+
+###### error complete you are not assigned to any table
+
+You must be assigned to a table before handling tickets.
+
+###### error complete ticket id does not exist
+
+The ticket with the provided id you are trying to complete does not exist.
+
+###### error complete you do not own this ticket
+
+The ticket you are trying to complete must be owned by you.
+
+###### error complete the ticket has already been completed or cancelled
+
+This means the ticket you are trying to cancel cannot be cancelled
+as it has already previously been, or has been completed.
+
+###### success complete `{id}`
+
+The ticket was successfully completed with no issues.
+
+#### pick
+
+This command lets a staff member pick a table
+
+##### example:
+
+```
+pick 0 abcdefghijklmnoprstuvwxy
+```
+
+This command would assign the client the table 0, and validate their identity with their token
+
+##### responses:
+
+###### error pick the provided token does not belong to any staff member
+
+You are using an invalid token. Try to relog
+
+###### error the chosen table is not available
+
+This means that the table you are chosing (0, in this case) is already taken,
+or you are picking an invalid number.
+
+###### success pick `{table}`
+
+You successfully claimed the table and can start accepting tickets
+
+#### unpick
+
+This command lets a staff member unset their chosen table
+
+##### example:
+
+```
+unpick
+```
+
+This would unassign the table the client has chosen
+
+##### responses:
+
+###### error unpick you do not have a table assigned
+
+This means you do not have a current table you have picked
+
+###### success unpick
+
+This means you have successfully reset your chosen table
+
+## Kiosk Endpoints
+
+These endpoints are used between the kiosk (client-facing machine), and the server
+
+### Kiosk to Server
+
+#### new
+
+This message is sent from the kiosk when a new ticket is requested to be created
+
+##### example:
+
+```
+new example@example.com Example Name
+```
+
+This sample command will create a new ticket under the email of
+example@example.com, and their name Example Name
+
+##### responses:
+
+###### success new `{jsonEncodedTicket}`
+
+The ticket was successfully created for the client
+
+#### query
+
+This message is sent from the kiosk when the kiosk tries to autocomplete the client's name
+
+##### example:
+
+```
+query example@example.com
+```
+
+This sample command will try to find the name for the client
+who's email is example@example.com
+
+##### responses:
+
+###### error query visitor email does not exist
+
+The email you are trying to query has no corresponding user,
+this is the first time that user is visiting
+
+###### success query `{name}`
+
+This message returns the corresponding name that was found
+in our database for the example proivded.
+
+## Display Endpoints
+
+These endpoints will be used by the display machine
+
+### Server to Display
+
+#### cancel
+
+This command will tell the display to clear the table's ticket
+
+##### example:
+
+```
+cancel 0
+```
+
+This will cancel the ticket that was planned to happen on table 0
+
+#### claimed
+
+This command will tell the display that a ticket was claimed by a staff memeber
+
+##### example:
+
+```
+claimed StaffMember 0 {"id":0,"email":"example@example.com","name":"Example Name","staff":"StaffMember","start":"2019-10-01T04:12:19Z","end":"1970-01-01T00:00:00Z"}
+```
+
+This will tell the display that the staff member 'StaffMember' has claimed the ticket on table 0
+
+#### complete
+
+This tells the display that the ticket on a table has been successfully completed
+
+##### example:
+
+```
+complete 0
+```
+
+This tells the display that the ticket on table 0 has been completed
+
+#### pick
+
+This tells the display that a table has been claimed by a staff member
+and to show it as online on the display
+
+##### example:
+
+```
+pick 0
+```
+
+This tells the display that the table 0 has been picked by a staff member
+
+#### unpick
+
+This tells the display that a client has left serving on a table
+
+##### example:
+
+```
+unpick 0
+```
+
+This tells the display that the table 0 is no longer going to be accepting/serving tickets.