initial high level docs for pysogs and soggy

Author: majestrate

docs/bot-api.md

@@ -0,0 +1,165 @@
+# Low Level docs for sogs bot api
+
+For a high level bot framework in python see [soggy](soggy.md)
+
+zmq commands:
+
+* [sogs.sub](#sub)
+* [sogs.unsub](#unsub)
+
+* [sogs.user.info](#user-info)
+* [sogs.user.send](#user-send)
+* [sogs.user.perm](#user-perm)
+* [sogs.user.ban](#user-ban)
+* [sogs.user.unban](#user-unban)
+
+* [sogs.room.info](#room-info)
+* [sogs.room.send](#room-send)
+* [sogs.room.perm](#room-perm)
+
+* [sogs.file.info](#file-info)
+* [sogs.file.upload](#file-upload)
+* [sogs.file.del](#file-del)
+* [sogs.file.ban](#file-ban)
+* [sogs.file.unban](#file-ban)
+
+
+# Objects
+
+## UserInfo
+
+a dict containing info on a user
+
+* id - the integer id for this user
+* pubkey - the user's 32 byte public x25519 key, session id is 0x05 then the pubkey bytes all hex encoded
+* names - a dict of room token as key and displayed name in that room
+* mod - if the user is a moderator positive non zero otherwise zero
+
+## RoomInfo
+
+a dict containing info on a room
+
+* id - the integer id for this room
+* token - the name of this room used in the url
+* users - a list of UserInfo of all the users in the room (optional)
+
+## FileInfo
+
+a dict describing a file
+
+* id - internal id for referring to this file
+* public-url - a public url to fetch the file at
+* size - the size of this file in bytes
+* mimetype - the implied mimetpye of this file
+* uploaded - the time this file was uploaded at in milliseconds since unix epoch
+* hashes - a dict of hash algorithm name to the digest value of the file with that algorithm (currently supported algorithms: blake2 / sha2-256 / sha1 / md5 )
+* user - the user id of who uploaded this file
+
+## PostInfo
+
+a dict describing a post made to a room
+
+* id - the post's id
+* user - the id of the user that posted the message
+* room - the id of the room that the message was posted in
+* when - the time this message was recieved in the room as milliseconds since unix epoch
+* text - the plaintext body of the message as a string
+* files - a list of file ids this message uploaded files with (optional)
+* cites - a post id this post is citing (optional)
+
+
+# Events
+
+## message
+
+sent when a user posts a message to a room
+
+contains a PostInfo, a UserInfo and a RoomInfo
+
+## joined
+
+sent when a user joins a room
+
+provides a UserInfo and a RoomInfo
+
+## banned
+
+sent when a user is banned from a room or the entire server
+
+## unbanned
+
+like banned but for when unbanned
+
+## uploaded
+
+sent when a file is uploaded to sogs
+
+contains one or more FileInfos
+
+## deleted
+
+sent when a post or file is deleted
+
+contains one or more PostInfos
+
+# Commands
+
+## sogs.sub <span id="sub" />
+
+subscribe to events
+
+## sogs.unsub <span id="unsub" />
+
+unsubscribe to events
+
+## sogs.user.info <span id="user-info" />
+
+fetch info of a user
+
+## sogs.user.send <span id="user-send" />
+
+send a whisper to a user
+
+## sogs.user.perm <span id="user-perm" />
+
+get/set user permissions (read/write/upload)
+
+## sogs.user.ban <span id="user-ban" />
+
+ban user
+
+## sogs.user.unban <span id="user-unban" />
+
+unban user
+
+## sogs.room.info <span id="room-info" />
+
+get/set room info
+
+## sogs.room.send <span id="room-send" />
+
+send a message to the room
+
+## sogs.room.perm <span id="room-perm" />
+
+get/set room permissions (read/write/upload)
+
+## sogs.file.info <span id="file-info" />
+
+get uploaded file info
+
+## sogs.file.upload <span id="file-upload" />
+
+upload a file
+
+## sogs.file.del <span id="file-del" />
+
+delete a file
+
+## sogs.file.ban <span id="file-ban" />
+
+ban file uploads by mimetype/hash/etc optionally per room
+
+## sogs.file.unban <span id="file-unban" />
+
+unban uploads by mimetype/hash/etc optionally per room

docs/docker-setup.md

@@ -0,0 +1,5 @@
+# pysogs docker
+
+docker images for pysogs are tagged as `docker.getsession.org/pysogs:stable`
+
+#### todo: more docs on this

docs/readme.md

@@ -0,0 +1,10 @@
+# pysogs docs portal
+
+Set up pysogs in a docker container:
+
+[Docker Setup](docker-setup.md)
+
+ZMQ Api for bots and other automation:
+
+[Python Library for bots](soggy.md)
+[Low Level Bot API docs](bot-api.md)

docs/soggy.md

@@ -0,0 +1,3 @@
+# soggy
+
+high level python bot library for sogs