Skip to content

A RESTful API around Topgg (Discord Bot List) voting webhooks

License

Notifications You must be signed in to change notification settings

shipgirlproject/Haruna

Repository files navigation

Haruna

The ShipGirl Project; Haruna. (c) Kancolle for Haruna.

Fast and reliable.

Run and forget, Haruna can run with 99.9% uptime.

Rest based API for your easy vote checks without opening a webserver on your bot.

Webhook based API is also available if you are someone who needs both the API and Realtime vote handling.

Documentation

Rest API

POST /newVote

The endpoint that is exposed to Top.gg (Discord Bot List); Refer to the image below.

GET /voteInfo

The endpoint which you can use to check for votes.

Headers:

{
  "authorization": "the authorization key you have set on Top.gg (Discord Bot List) webhook"
}

Query String: user_id

Returns: JSON string.

// User Voted
{
  "user": "23213512",
  "timestamp": 432483204, 
  "isWeekend": true,
  "timeLeft": 274013
}
// User Didn't Vote
{
  "user": false
}

GET /stats

Returns: Current status of server in JSON string.

Webhook API [1.4.0 and later]

If enabled, it will send a POST request containing the user who voted in the URL of your choice.

For checking the request validity, you can check the authorization header as it will send the same restAuth you have set on your config

Returns: JSON string.

{
  "user": "389138132391230131031903",
  "isWeekend": true
}

Haruna's API Wrappers

Java

Javascript

C#

you can also create your own and PR if you want to contribute it.

How to Host

Manually

  1. Download the latest haruna.jar from Github Releases. Click me

  2. Download HarunaConfig.json from github. Click me

  3. Configure HarunaConfig.json according to your liking and put it BESIDE haruna.jar

  4. Start the server via java -jar haruna.jar

  5. To verify Haruna is working, navigate to http://localhost:port_you_specified/ or http://your_server_ip:the_port_you_specified/. Example

Docker

  1. Get docker-compose file. Click me

  2. Update values according to your needs (ports and environment)

  3. Start the server via docker compose up -d

Haruna's config file example & explanation.

{
  "restAuth": "weeb_handler", 
  "topggAuth": "JRIrjrqwrpURJQWOPRj_rfnQEUi_KRqop",
  "webhook": "https://discordapp.com/api/webhooks/84293482482420424024802/sneaky_token_OWO",
  "postWebhook": "localhost:6969",
  "debug": true,
  "port": 1024,
  "threads": 8,
  "userTimeout": 432000000
}
  • restAuth (REST_AUTH) is the Discord Bot List Webhook Authorization.
  • topggAuth (TOPGG_AUTH) is your token for Discord Bot List.
  • webhook (WEBHOOK) is your Discord Webhook link (Optional)
  • postWebhook (POST_WEBHOOK) is where Haruna will try to send a POST request of the user who voted Refer Here (Optional)
  • debug (DEBUG) is if you want to enable debug logs of Haruna (Optional, Default: false)
  • port (PORT) is what port you want this server hosted (Optional, Default: 1024)
  • threads (THREADS) is how many threads you want this server to have (Optional, Default: Your CPU Thread Count)
  • userTimeout (USER_TIMEOUT) is how long the user will stay in database in ms (Optional, Default: 43200000)

Between parenthesis is the key to set as environment variable in case you want to use this configuration way.

Support

We provide support for usage of this API in our Official Server's #development-support forums which is in HERE

Made with ❤️ by @ichimakase