Dashboard API

Extend the Drako Bot dashboard with custom pages and API endpoints.

✨ Features

• Custom Pages — Add your own React pages to the dashboard

• Navigation Integration — Pages appear as tabs inside your addon

• API Routes — Create custom backend endpoints for your addon

• Full React Support — Use hooks, state, and all React features

• Authentication — Automatic auth handling for protected endpoints

🚀 Quick Start

Folder Structure

addons/
└── my-addon/
    ├── my-addon.js          # Main addon file (events, etc.)
    └── dashboard/
        ├── config.js         # Dashboard configuration
        └── pages/
            ├── index.jsx     # Main page component
            └── settings.jsx  # Additional pages

Example: Complete Dashboard Addon

addons/my-addon/dashboard/config.js

module.exports = {
    // Register pages
    pages: [
        {
            path: '/addon/my-addon',
            component: 'index',
            title: 'My Addon'
        },
        {
            path: '/addon/my-addon/settings',
            component: 'settings',
            title: 'My Addon Settings'
        }
    ],
// Custom API endpoints
    apiRoutes: [
        {
            method: 'get',
            path: '/stats',
            handler: async (req, res) => {
                res.json({
                    message: 'Hello from My Addon!',
                    timestamp: new Date().toISOString()
                });
            }
        },
        {
            method: 'post',
            path: '/save',
            handler: async (req, res) => {
                const { setting } = req.body;
                // Save to database...
                res.json({ success: true, setting });
            }
        }
    ]
};

addons/my-addon/dashboard/pages/index.jsx

import React, { useState, useEffect } from 'react';

export default function MyAddonPage({ api }) {
    const [data, setData] = useState(null);
    const [loading, setLoading] = useState(true);

    useEffect(() => {
        const fetchData = async () => {
            try {
                // Call the addon API for the selected server
                const response = await api('stats');
                setData(response);
            } catch (error) {
                console.error('Failed to fetch:', error);
            } finally {
                setLoading(false);
            }
        };
        fetchData();
    }, []);

    return (
        <div>
            <div>
                <h1>
                    My Addon Dashboard
                </h1>
                
                {loading ? (
                    <p>Loading...</p>
                ) : (
                    <div>
                        <p>{data?.message}</p>
                        <p>
                            Last updated: {data?.timestamp}
                        </p>
                    </div>
                )}
            </div>
        </div>
    );
}

📄 Configuration Reference

Pages

Register custom pages in your addon:

module.exports = {
pages: [
    {
        path: '/addon/my-addon',      // Page identifier (required)
        component: 'index',            // File in pages/ folder (required)
        title: 'My Addon',             // Page title (optional)
        requiredRoles: null            // Array of role IDs or null (optional)
    }
]
};

Property	Type	Required	Description
path	string	✅	Page identifier
component	string	✅	Filename in pages/ (without extension)
title	string	❌	Addon page tab title

Navigation

Open the addon from the dashboard’s Addons page. Its registered pages appear as tabs.

API Routes

Create custom backend endpoints:

module.exports = {
apiRoutes: [
    {
        method: 'get',                 // HTTP method (required)
        path: '/stats',                // Endpoint path (required)
        requiredRoles: null,           // Array of role IDs or null (optional)
        handler: async (req, res) => { // Handler function (required)
            res.json({ data: 'value' });
        }
    }
]
};

Property	Type	Required	Description
method	string	✅	get, post, put, delete, patch
path	string	✅	Endpoint path (prefixed with /api/addons/{addonname})
handler	function	✅	Express route handler
middleware	array	❌	Additional middleware functions
requiredRoles	string[]|null	❌	Additional Discord role IDs for API access

🎨 Styling Guide

Use your own CSS or inline React styles. Import a stylesheet from your page with import './styles.css'.

Use flexible widths so your page fits mobile screens.

🔌 API Endpoint Patterns

Accessing Your API

Page components receive an api prop. Call it with your route path to use the selected server and current dashboard session.

Making API Calls

async function example(api) {
    const stats = await api('stats');
    await api('save', {
        method: 'POST',
        body: JSON.stringify({ setting: 'value' })
    });
    return stats;
}

Handler Examples

module.exports = {
apiRoutes: [
    // Simple GET
    {
        method: 'get',
        path: '/info',
        handler: async (req, res) => {
            res.json({ version: '1.0.0' });
        }
    },
    
    // With request body
    {
        method: 'post',
        path: '/settings',
        handler: async (req, res) => {
            const { enabled, message } = req.body;
            // Validate
            if (typeof enabled !== 'boolean') {
                return res.status(400).json({ error: 'Invalid enabled value' });
            }
            // Save and respond
            res.json({ success: true, enabled, message });
        }
    },
    
    // With URL parameters
    {
        method: 'get',
        path: '/user/:userId',
        handler: async (req, res) => {
            const { userId } = req.params;
            // Fetch user data...
            res.json({ userId, data: {} });
        }
    },
    
    // Database integration
    {
        method: 'get',
        path: '/guild-stats',
        handler: async (req, res) => {
            const mongoose = require('mongoose');
            const stats = await mongoose.model('GuildStats').find({});
            res.json({ stats });
        }
    }
]
};

🔐 Authentication & Permissions

Using requiredRoles

These addon pages require administrator access to every server the bot is in.

For API routes, the requiredRoles property accepts an array of Discord role IDs. Users must have at least one of the specified roles to access the resource.

// No additional role restriction
requiredRoles: null

// Require specific role(s)
requiredRoles: ['123456789012345678']

// Require any of multiple roles (OR logic)
requiredRoles: ['ROLE_ID1', 'ROLE_ID2', 'ROLE_ID3']

Complete Example with Permissions

module.exports = {
    pages: [
        {
            path: '/addon/admin-panel',
            component: 'admin',
            title: 'Admin Panel',
            // Only users with Admin or Owner role can access
            requiredRoles: ['111111111111111111', '222222222222222222']
        },
        {
            path: '/addon/admin-panel/public',
            component: 'public',
            title: 'Public Info',
            // No additional role restriction
            requiredRoles: null
        }
    ],
apiRoutes: [
        {
            method: 'get',
            path: '/public-data',
            requiredRoles: null,  // No additional role restriction
            handler: async (req, res) => {
                res.json({ public: true });
            }
        },
        {
            method: 'post',
            path: '/admin-action',
            requiredRoles: ['111111111111111111'],  // Admin only
            handler: async (req, res) => {
                // Only admins reach here
                res.json({ success: true });
            }
        }
    ]
};

Getting Role IDs

Enable Developer Mode in Discord:

• Settings → Advanced → Developer Mode

• Right-click the role → Copy Role ID

Checking User in API Handler

const route = {
    method: 'get',
    path: '/user-info',
    handler: async (req, res) => {
        // req.user is available after auth
        const user = req.user;
        
        if (!user) {
            return res.status(401).json({ error: 'Not authenticated' });
        }
        
        // Access user data
        res.json({ 
            userId: user.id,
            username: user.name,
            roles: [...req.access.member.roles.cache.keys()]  // Array of role IDs
        });
    }
};

🧩 Complete Examples

Stats Dashboard

// config.js
module.exports = {
    pages: [
        { path: '/addon/stats', component: 'index', title: 'Server Stats' }
    ],
apiRoutes: [
        {
            method: 'get',
            path: '/overview',
            handler: async (req, res) => {
                const client = req.guild.client;
                
                res.json({
                    guilds: client.guilds.cache.size,
                    users: client.users.cache.size,
                    channels: client.channels.cache.size,
                    uptime: process.uptime()
                });
            }
        }
    ]
};

// pages/index.jsx
import React, { useState, useEffect } from 'react';

export default function StatsPage({ api }) {
    const [stats, setStats] = useState(null);

    useEffect(() => {
        api('overview')
            .then(setStats)
            .catch(console.error);
    }, []);

    if (!stats) return <div>Loading...</div>;

    return (
        <div>
            <h1>Server Stats</h1>
            
            <div>
                <StatCard label="Guilds" value={stats.guilds} emoji="🏠" />
                <StatCard label="Users" value={stats.users} emoji="👥" />
                <StatCard label="Channels" value={stats.channels} emoji="📺" />
                <StatCard label="Uptime" value={formatUptime(stats.uptime)} emoji="⏱️" />
            </div>
        </div>
    );
}

function StatCard({ label, value, emoji }) {
    return (
        <div>
            <div>{emoji}</div>
            <div>{value}</div>
            <div>{label}</div>
        </div>
    );
}

function formatUptime(seconds) {
    const hours = Math.floor(seconds / 3600);
    const minutes = Math.floor((seconds % 3600) / 60);
    return `${hours}h ${minutes}m`;
}

Settings Panel

// config.js
module.exports = {
    pages: [
        { path: '/addon/my-settings', component: 'index', title: 'My Settings' }
    ],
apiRoutes: [
        {
            method: 'get',
            path: '/config',
            handler: async (req, res) => {
                // Load from database or file
                res.json({
                    enabled: true,
                    welcomeMessage: 'Welcome!',
                    notifyChannel: '123456789'
                });
            }
        },
        {
            method: 'post',
            path: '/config',
            handler: async (req, res) => {
                const { enabled, welcomeMessage, notifyChannel } = req.body;
                // Save to database...
                res.json({ success: true });
            }
        }
    ]
};

// pages/index.jsx
import React, { useState, useEffect } from 'react';

export default function SettingsPage({ api }) {
    const [settings, setSettings] = useState({
        enabled: false,
        welcomeMessage: '',
        notifyChannel: ''
    });
    const [saving, setSaving] = useState(false);

    useEffect(() => {
        api('config')
            .then(setSettings)
            .catch(console.error);
    }, []);

    const handleSave = async () => {
        setSaving(true);
        try {
            await api('config', { method: 'POST', body: JSON.stringify(settings) });
            alert('Settings saved!');
        } catch (error) {
            alert('Failed to save');
        } finally {
            setSaving(false);
        }
    };

    return (
        <div>
            <div>
                <h1>Settings</h1>
                
                {/* Toggle */}
                <div>
                    <div>
                        <h3>Enable Feature</h3>
                        <p>Toggle the feature on/off</p>
                    </div>
                    <input type="checkbox" aria-label="Enable Feature" checked={settings.enabled}
                        onChange={e => setSettings(s => ({ ...s, enabled: e.target.checked }))} />
                </div>
                
                {/* Text Input */}
                <div>
                    <label>
                        Welcome Message
                    </label>
                    <input
                        type="text"
                        value={settings.welcomeMessage}
                        onChange={e => setSettings(s => ({ ...s, welcomeMessage: e.target.value }))}
                        placeholder="Enter message..."
                    />
                </div>
                
                {/* Save Button */}
                <div>
                    <button
                        onClick={handleSave}
                        disabled={saving}
                    >
                        {saving ? 'Saving...' : 'Save Settings'}
                    </button>
                </div>
            </div>
        </div>
    );
}

📋 Requirements Summary

Minimum Required

addons/my-addon/
└── dashboard/
    ├── config.js      # Exports pages and apiRoutes
    └── pages/
        └── index.jsx  # At least one page component

config.js Template

module.exports = {
    pages: [],      // Required (can be empty)
    apiRoutes: []   // Required (can be empty)
};

Page Component Template

import React from 'react';

export default function MyPage({ api }) {
    return (
        <div>
            <div>
                <h1>My Page</h1>
            </div>
        </div>
    );
}

🔄 Integration with Event API

Combine dashboard with event handlers:

addons/my-addon/my-addon.js

module.exports = {
    name: 'MyAddon',
    version: '1.0.0',
    
    // Event handlers
    events: {
        'discord:messageCreate': async (eventData, context) => {
            // Handle Discord events
        }
    },
    
    // Initialization
    run: async (client, eventManager) => {
        console.log('[MyAddon] Loaded with dashboard support!');
    }
};

The dashboard config is loaded from dashboard/config.js when the addon initializes. Restart the bot after changing dashboard code.

💡 Tips & Best Practices

• Use meaningful addon names — The addon name becomes part of the API URL

• Handle loading states — Always show loading indicators

• Error handling — Catch and display errors gracefully

• API validation — Always validate request data on the backend

• Permission checks — Use permissions for sensitive features

Troubleshooting

Page not loading

• Check browser console for errors

• Verify file exists in dashboard/pages/

• Ensure component has export default

API returns 404

• Check addon name is lowercase in URL

• Verify route is registered in config.js

• Check server logs for registration messages

Styles not applying

• Import your addon stylesheet or use inline styles

• Check class names are correct

• Verify you're using the right CSS variable names

Authentication issues

• Ensure you're logged into the dashboard

• Check if route requires specific permissions

• Verify session is active