Bear Moderation Plugin API

The Plugin API allows you to create custom plugins for the Bear Moderation bot. Plugins can add new commands, handle events, and extend the bot's functionality.

Quick Start

1. Get a Port

curl http://localhost:6500/handshake

Returns:

{"port": 22005, "status": "success"}

2. Start Your Plugin Server

from flask import Flask, jsonify, request
app = Flask(__name__)

@app.route("/commands", methods=["GET"])
def get_commands():
    return jsonify({"commands": [{"name": "ping", "description": "Ping"}]})

@app.route("/execute", methods=["POST"])
def execute():
    return jsonify({"response": "Pong!"})

app.run(host="0.0.0.0", port=22005)

3. Register Your Plugin

curl -X POST http://localhost:6500/register \
  -H "Content-Type: application/json" \
  -d '{"port": 22005, "name": "My Plugin", "version": "1.0", "author": "You"}'

API Endpoints (Bot Side, Port 6500)

Get an unused port for your plugin.

Register your plugin with the bot.

{
  "port": 22005,
  "name": "My Plugin",
  "version": "1.0",
  "author": "You",
  "description": "Optional description"
}

List all registered plugins.

Get detailed info about a specific plugin.

Unregister a plugin.

Execute a command on a plugin.

{
  "command": "ping",
  "args": {},
  "context": {
    "author_id": 1234567890,
    "author_name": "User",
    "channel_id": 1234567890,
    "guild_id": 1234567890
  }
}

Check if the plugin API is alive.

Plugin Endpoints (Your Plugin)

List all commands your plugin provides.

{
  "commands": [
    {"name": "ping", "description": "Ping the plugin"},
    {"name": "echo", "description": "Echo back your message"}
  ]
}

Execute a command from the bot.

Request:

{
  "command": "ping",
  "args": "",
  "context": {
    "author_id": 1234567890,
    "author_name": "User",
    "channel_id": 1234567890,
    "guild_id": 1234567890
  }
}

Response:

{
  "response": "Pong!",
  "status": "success"
}

Receive events from the bot (messages, member joins, etc.).

{
  "type": "on_message",
  "data": {
    "author": "User",
    "content": "Hello!",
    "channel": "general"
  }
}

Check if your plugin is alive.

Event System

Plugins can receive events from the bot by implementing the /events endpoint.

Event Types

Event	Description	Data
on_message	When a message is sent	author, content, channel, guild
on_member_join	When a member joins	member, guild
on_command	When a command is run	command, author, channel

Example Event Handler

@app.route("/events", methods=["POST"])
def handle_event():
    data = request.json
    event_type = data.get("type")

    if event_type == "on_message":
        content = data.get("data", {}).get("content", "")
        if "hello" in content.lower():
            print("Someone said hello!")

    return jsonify({"status": "received"})

Plugin Permissions

Plugins can request permissions to access certain bot features.

Permission	Description
read_messages	Read messages in channels
send_messages	Send messages
manage_roles	Add/remove roles
kick_members	Kick members
ban_members	Ban members
manage_messages	Delete messages
read_audit_log	Read audit log
execute_commands	Execute bot commands

Setting Permissions

curl -X POST http://localhost:6500/plugins/plugin_22005/permissions \
  -H "Content-Type: application/json" \
  -d '{"permissions": ["read_messages", "send_messages"]}'

Full Example

Here's a minimal working plugin:

#!/usr/bin/env python3
import requests
import time
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route("/commands", methods=["GET"])
def get_commands():
    return jsonify({"commands": [{"name": "ping", "description": "Ping"}]})

@app.route("/execute", methods=["POST"])
def execute():
    return jsonify({"response": "Pong!"})

def main():
    response = requests.get("http://localhost:6500/handshake")
    port = response.json()["port"]

    app.run(host="0.0.0.0", port=port)

    requests.post("http://localhost:6500/register", json={
        "port": port,
        "name": "My Plugin",
        "version": "1.0",
        "author": "You"
    })

if __name__ == "__main__":
    main()

Run it:

python plugin.py

Submit Your Plugin

Ready to share your creation with the world?
Join the official Bear Tools Discord server to submit your plugin.