Furmissile / orca

A C Multi-REST API library for Discord, Slack, Reddit, etc.

Easy to reason, easy to debug, easy to use.

Join our Discord server:

About

Orca is implemented in plain C, its symbols are organized to be easily matched to the documentation of the API being covered.

This is done in order to:

• Minimize the need of thoroughly documenting every Orca API.
• Reduce our user's cognitive burden of having to read both Orca API documentation and supported REST API documentations.
• The codebase becomes easier to navigate.

Orca's implementation has minimum external dependencies to make bot deployment deadly simple.

Design

• Easy to reason about the code: the most native data structures, the simplest algorithms, and intuitive interfaces.

• Easy to debug (networking and logic) errors: extensive assertion and logging facilities.

• Easy to use for the end users: highly scalable, all transfers made with Orca are thread-safe.

Minimal example

#include <string.h> // strcmp()
#include <orca/discord.h>

void on_ready(
  struct discord *client, 
  const struct discord_user *bot) 
{
  log_info("Logged in as %s!", bot->username);
}

void on_message(
  struct discord *client, 
  const struct discord_user *bot, 
  const struct discord_message *msg)
{
  // if message content equals 'ping', then bot responds with 'pong'
  if (0 == strcmp(msg->content, "ping")) {
    struct discord_create_message_params params = { .content = "pong" };
    discord_create_message(client, msg->channel_id, &params, NULL);
  }
}

int main() {
  struct discord *client = discord_init(BOT_TOKEN);
  discord_set_on_ready(client, &on_ready);
  discord_set_on_message_create(client, &on_message);
  discord_run(client);
}

This is a minimalistic example, refer to examples/ for a better overview.

Build Instructions

On Windows

• Install WSL2 and get either Ubuntu or Debian here.
• Make sure you are in your Linux $HOME folder before proceeding!
• Continue to On Linux and follow your distro's building steps.

On Linux

The only dependencies are curl-7.64.0 or higher built with OpenSSL, and wget that will be used by the Makefile for fetching cee-utils files.

Ubuntu and Debian

$ sudo apt-get install -y build-essential wget
$ sudo apt-get install -y libcurl4-openssl-dev libssl-dev

Void Linux

$ sudo xbps-install -S wget
$ sudo xbps-install -S libcurl-devel

Setting up your environment

Clone orca into your workspace

$ git clone https://github.com/cee-studio/orca.git
$ cd orca

Compile orca

$ make

Configuring orca

The following outlines the default fields of config.json

{
  "logging": { // logging directives
    "level": "trace",        // trace, debug, info, warn, error, fatal
    "filename": "bot.log",   // the output file
    "quiet": false,          // change to true to disable logs in console
    "overwrite": false,      // overwrite existing file with "filename"
    "use_color": true,       // log with color
    "http": {
      "enable": true,        // generate http specific logging
      "filename": "http.log" // the output file
    },
    "disable_modules": ["WEBSOCKETS", "USER_AGENT"] // disable logging for these modules
  },
  ...         // API directives (discord, slack, github, etc)
}

Test Echo-Bot

1. Get your bot token and add it to config.json, by assigning it to discord's "token" field. There are well written instructions from the discord-irc about how to get your bot token and adding it to a server.
2. Build example executables:

   $ make examples

3. Run Echo-Bot:

   $ cd examples
   $ ./bot-echo.out

Get Echo-Bot Response

Type a message in any channel the bot is part of and the bot should send an echo response in return.

Terminate Echo-Bot

With Ctrl+c or by closing the Terminal.

Create your first bot

• Head to my_bot/, a special folder set-up for your convenience that may be modified freely.
• Read our guide for building your first bot.

Installing orca

Orca can be installed in case developing inside of my_bot/ doesn't suit your needs:

$ sudo make install

Included headers must be orca/ prefixed:

#include <orca/discord.h>
#include <orca/github.h>

Standalone executable

$ gcc myBot.c -o myBot.out -pthread -ldiscord -lcurl -lcrypto -lm

Recommended debuggers

First, make sure your executable is compiled with the -g flag so you can get more detailed debugger messages.

Valgrind

Using valgrind to check for memory leaks:

$ valgrind --leak-check=full ./myBot.out

For a more comprehensive guide check Valgrind's Quick Start.

GDB

Using GDB to check for runtime errors, such as segmentation faults:

$ gdb ./myBot.out

And then execute your bot from the gdb environment:

(gdb) run

If the program has crashed, get a backtrace of the function calls leading to it:

(gdb) bt

For a more comprehensive guide check Beej's Quick Guide to GDB

Links

• Discord Server
• Documentation
• Building your first bot
• Internals
• Contributing

Contributing

Check our Contributing Guidelines to get started! If you are here for the Discord API, please check our Discord API Roadmap.

Give us a star if you like this project!