v0.0.1: Add setRank, getRank & base client

README.md

@@ -1,2 +1,69 @@
 # cetus-rbx
 The official Lua SDK for interacting with the Cetus API from Roblox games.
+This SDK, like our platform, is in Alpha and is not quite fully baked yet.
+Expect a lot of variation between versions until we hit v1.x.x!
+
+## Installation
+### Method 1: Rojo
+You must have Rojo installed and configured
+1. Clone this repo with your GUI tool of choice or the command:
+```bash
+$ git clone https://github.com/cetus-app/cetus.rbx
+```
+2. Navigate to the repository
+3. Run `Rojo serve`
+
+### Method 2: Github releases
+We release Roblox model files via. the [Github releases](https://github.com/cetus-app/cetus-rbx/releases) page. You can download the model, add it to your game via. "Insert from file" and get started!
+
+
+## API
+### Responses
+The majority of the methods here return the API response in the event of a success. You can find schemas and more by looking at our API docs.
+Errors are slightly different:
+#### Handling errors
+Errors are returned as a table with the following keys:
+```lua
+{
+ error = {
+ status: number, -- The HTTP status code. 0 for a Roblox HTTP error
+ name: string, -- The error name as returned by our API or "HttpError" for Roblox HTTP errors like ConnectFail.
+ message: string -- A more indepth error message. Always returned unless it's an unauthorized error, in which case it may not be.
+ }
+}
+```
+We choose not to use the built in Lua `error` function because it only allows us to throw a string, and it does not allow us to express these other values.
+Our recomended way to make use of the API is to run a method and then check for `response.error` to see if it errored. If `error` is nil, the `response` will be the returned API values.
+
+### Getting a client
+The main cetus module returns an init function. To create a `Client`, you must call this init function with your client config.
+
+This client structure means that you can have multiple Cetus clients or "instances" of this SDK without them interfering with each other.
+This means that you could control multiple groups at once, for example.
+
+
+#### Client options
+- token: string, Your authorisation token as gained from our Dashboard https://cetus.app/dashboard. You must add the group to our service first.
+
+These are passed as a table.
+
+#### Client example
+```lua
+local ServerStorage = game:GetService("ServerStorage")
+local Cetus = require(ServerStorage.cetus)
+local client = Cetus({
+ token = "My secret authentication token"
+})
+```
+### Client Methods
+> More Documentation coming soon
+#### setRank
+`client.setRank(userId: number)`
+
+#### getRank
+`client.getRank(userId: number)`
+
+
+## To-do list
+* Add rate limit support
+* Implement option to make errors 'thrown'

default.project.json

@@ -0,0 +1,19 @@
+{
+ "name": "cetus-rbx",
+ "tree": {
+ "$className": "DataModel",
+
+ "ServerStorage": {
+ "$className": "ServerStorage",
+ "$path": "src"
+ },
+ "HttpService": {
+ "$className": "HttpService",
+ "$properties": {
+ "HttpEnabled": true
+ }
+ }
+ }
+
+
+}

src/cetus/getRank.lua

@@ -0,0 +1,5 @@
+return function(client)
+ return function (userId)
+ return client.makeRequest("GET", "/v1/roblox/rank/"..userId)
+ end
+end

src/cetus/http.lua

@@ -0,0 +1,68 @@
+local httpService = game:GetService("HttpService");
+local function init (client)
+ --[[
+ The main function used to interact with the Cetus API.
+ If successful, this function will return the body of the response.
+ If the request fails it will return the following:
+ {
+ error: {
+ status: number (The http status code),
+ message: string, The HTTP error message
+ name: string The error name (often something like UnauthorisedError)
+ }
+ }
+ In the event of an error occuring *making* the request, (an error which would normally be thrown)
+ This will return the status code as 0, the name as "HttpError" and the message as the Roblox error message
+ If an error is returned from the API it is returned as-is.
+
+ ]]
+ local function makeRequest (method, url, body)
+ local headers = {
+ Authorization = "Bearer "..client._token
+ }
+ local request = {
+ Url = client.baseUrl..url,
+ Method = method,
+ Headers = headers
+ }
+
+ if body then
+ headers["Content-Type"] = "application/json"
+ if type(body) == "string" then
+ request.body = httpService:JSONEncode(body)
+ else
+ request.body = body
+ end
+ end
+
+ local succ, returnVal = pcall(function ()
+ local response = httpService:RequestAsync(request)
+ local decoded = httpService:JSONDecode(response.Body);
+ if response.Success then
+ return decoded
+ else
+ return {
+ error = {
+ status = response.StatusCode,
+ message = decoded.message,
+ name = decoded.name
+ }
+ }
+ end
+ end)
+ if succ then
+ return returnVal
+ else
+ return {
+ error = {
+ status = 0,
+ message = returnVal,
+ name = "HttpError"
+ }
+ }
+ end
+ end
+ return makeRequest
+end
+
+return init

src/cetus/init.lua

@@ -0,0 +1,31 @@
+local http = require(script.http)
+local getRank = require(script.getRank)
+local setRank = require(script.setRank)
+--[[
+ https://cetus.app: Lua SDK
+ Source: https://github.com/cetus-app/cetus-rbx
+ As per our license you should not modify this to be used on other projects without open sourcing your code.
+ Written by Neztore, 2020.
+ v0.0.1
+
+ Availible client options:
+ * token (required): Your authorisation token for your group. Get one here: https://cetus.app/dashboard
+
+
+
+]]
+return function (config)
+ local client = {
+ baseUrl = "http://localhost:4000"
+ }
+ if config.token then
+ client._token = config.token
+ else
+ error("Cetus-Rbx: Failed to start: No token provided.")
+ end
+ client.makeRequest = http(client)
+ client.getRank = getRank(client)
+ client.setRank = setRank(client)
+
+ return client
+end

src/cetus/setRank.lua

@@ -0,0 +1,7 @@
+return function(client)
+ return function (userId, rank)
+ return client.makeRequest("POST", "/v1/roblox/setRank/"..userId, {
+ rank = rank
+ })
+ end
+end