Dashboard API

Extend the DrakoBot dashboard with custom pages, navigation items, and API endpoints.

---

✨ Features

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

• Navigation Integration — Seamlessly add items to the sidebar

• API Routes — Create custom backend endpoints for your addon

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

• Tailwind CSS — Style with the dashboard's existing design system

• Authentication — Automatic auth handling for protected endpoints

• Hot Reload — Changes reflect instantly during development

---

🚀 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'
        }
    ],
    
    // Add to sidebar navigation
    navItems: [
        {
            name: 'My Addon',
            path: '/addon/my-addon',
            emoji: '🚀',
            permission: null,  // null = any logged in user
            order: 50          // Lower = higher in sidebar
        }
    ],
    
    // 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';
import axios from 'axios';

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

    useEffect(() => {
        const fetchData = async () => {
            try {
                // API path: /api/addons/{addonname}/{path}
                const response = await axios.get('/api/addons/myaddon/stats');
                setData(response.data);
            } catch (error) {
                console.error('Failed to fetch:', error);
            } finally {
                setLoading(false);
            }
        };
        fetchData();
    }, []);

    return (
        <div className="px-4 lg:px-6 space-y-6">
            <div className="glass-card p-6">
                <h1 className="text-xl font-bold text-foreground mb-4">
                    My Addon Dashboard
                </h1>
                
                {loading ? (
                    <p className="text-muted-foreground">Loading...</p>
                ) : (
                    <div className="glass-subtle rounded-xl p-4">
                        <p className="text-foreground">{data?.message}</p>
                        <p className="text-xs text-muted-foreground mt-2">
                            Last updated: {data?.timestamp}
                        </p>
                    </div>
                )}
            </div>
        </div>
    );
}

---

📄 Configuration Reference

Pages

Register custom pages in your addon:

pages: [
    {
        path: '/addon/my-addon',      // URL path (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	✅	URL path for the page
component	string	✅	Filename in pages/ (without extension)
title	string	❌	Browser tab title
requiredRoles	string[]|null	❌	Discord role IDs required to access

Navigation Items

Add items to the dashboard sidebar:

navItems: [
    {
        name: 'My Addon',              // Display name (required)
        path: '/addon/my-addon',       // Link destination (required)
        emoji: '🚀',                   // Emoji icon (optional)
        icon: 'faPuzzlePiece',         // FontAwesome icon (optional)
        requiredRoles: null,           // Array of role IDs or null (optional)
        order: 50                      // Sort order (optional)
    }
]

Property	Type	Required	Description
name	string	✅	Display name in sidebar
path	string	✅	Navigation destination
emoji	string	❌	Emoji to display
icon	string	❌	FontAwesome icon name
requiredRoles	string[]|null	❌	Discord role IDs required to see item
order	number	❌	Sort priority (lower = higher)

API Routes

Create custom backend endpoints:

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	❌	Discord role IDs required to access

---

🎨 Styling Guide

Available CSS Classes

The dashboard uses Tailwind CSS with custom utility classes:

// Card styles
<div className="glass-card p-6">         {/* Main card container */}
<div className="glass-subtle p-4">       {/* Subtle inner card */}

// Text colors
<h1 className="text-foreground">         {/* Primary text */}
<p className="text-muted-foreground">    {/* Secondary text */}

// Buttons
<button className="px-4 py-2 rounded-xl bg-primary text-primary-foreground">
    Primary Button
</button>

// Inputs
<input className="w-full h-10 px-4 rounded-xl glass-input text-sm" />

// Gradients
<div className="bg-gradient-to-br from-blue-500 to-blue-600">

Responsive Design

<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    {/* Cards auto-adjust based on screen size */}
</div>

---

🔌 API Endpoint Patterns

Accessing Your API

Your API routes are available at:

/api/addons/{addonname-lowercase}/{path}

Example:

• Addon name: MyAddon

• Route path: /stats

• Full URL: /api/addons/myaddon/stats

Making API Calls

import axios from 'axios';

// GET request
const response = await axios.get('/api/addons/myaddon/stats');

// POST request
const response = await axios.post('/api/addons/myaddon/save', {
    setting: 'value'
});

// With error handling
try {
    const { data } = await axios.get('/api/addons/myaddon/stats');
    console.log(data);
} catch (error) {
    if (error.response?.status === 401) {
        console.log('Not authenticated');
    }
}

Handler Examples

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

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

// Anyone logged in (no 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',
            // Anyone logged in can access
            requiredRoles: null
        }
    ],
    
    navItems: [
        {
            name: 'Admin Panel',
            path: '/addon/admin-panel',
            emoji: '⚙️',
            // Only show in sidebar for admins
            requiredRoles: ['111111111111111111', '222222222222222222']
        }
    ],
    
    apiRoutes: [
        {
            method: 'get',
            path: '/public-data',
            requiredRoles: null,  // Public endpoint
            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

1

Enable Developer Mode in Discord:

• Settings → Advanced → Developer Mode

2

Copy the role ID:

• Right-click the role → Copy Role ID

Checking User in API Handler

{
    method: 'get',
    path: '/user-info',
    handler: async (req, res) => {
        // req.user is available after auth
        const user = req.user || req.session?.userData;
        
        if (!user) {
            return res.status(401).json({ error: 'Not authenticated' });
        }
        
        // Access user data
        res.json({ 
            userId: user.id,
            username: user.username,
            roles: user.roles  // Array of role IDs
        });
    }
}

---

🧩 Complete Examples

Stats Dashboard

// config.js
module.exports = {
    pages: [
        { path: '/addon/stats', component: 'index', title: 'Server Stats' }
    ],
    navItems: [
        { name: 'Stats', path: '/addon/stats', emoji: '📊', order: 10 }
    ],
    apiRoutes: [
        {
            method: 'get',
            path: '/overview',
            handler: async (req, res) => {
                const client = require('../../bot').getDiscordClient();
                
                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';
import axios from 'axios';

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

    useEffect(() => {
        axios.get('/api/addons/stats/overview')
            .then(res => setStats(res.data))
            .catch(console.error);
    }, []);

    if (!stats) return <div className="text-muted-foreground">Loading...</div>;

    return (
        <div className="px-4 lg:px-6">
            <h1 className="text-2xl font-bold text-foreground mb-6">Server Stats</h1>
            
            <div className="grid grid-cols-1 md:grid-cols-4 gap-4">
                <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 className="glass-card p-4">
            <div className="text-2xl mb-2">{emoji}</div>
            <div className="text-2xl font-bold text-foreground">{value}</div>
            <div className="text-sm text-muted-foreground">{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' }
    ],
    navItems: [
        { name: 'My Settings', path: '/addon/my-settings', emoji: '⚙️' }
    ],
    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';
import axios from 'axios';

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

    useEffect(() => {
        axios.get('/api/addons/my-settings/config')
            .then(res => setSettings(res.data))
            .catch(console.error);
    }, []);

    const handleSave = async () => {
        setSaving(true);
        try {
            await axios.post('/api/addons/my-settings/config', settings);
            alert('Settings saved!');
        } catch (error) {
            alert('Failed to save');
        } finally {
            setSaving(false);
        }
    };

    return (
        <div className="px-4 lg:px-6 space-y-6">
            <div className="glass-card p-6">
                <h1 className="text-xl font-bold text-foreground mb-6">Settings</h1>
                
                {/* Toggle */}
                <div className="flex items-center justify-between p-4 glass-subtle rounded-xl mb-4">
                    <div>
                        <h3 className="text-sm font-medium text-foreground">Enable Feature</h3>
                        <p className="text-xs text-muted-foreground">Toggle the feature on/off</p>
                    </div>
                    <button
                        onClick={() => setSettings(s => ({ ...s, enabled: !s.enabled }))}
                        className={`w-12 h-6 rounded-full transition-colors ${
                            settings.enabled ? 'bg-primary' : 'bg-secondary'
                        }`}
                    >
                        <span className={`block w-4 h-4 rounded-full bg-white transition-transform ${
                            settings.enabled ? 'translate-x-7' : 'translate-x-1'
                        }`} />
                    </button>
                </div>
                
                {/* Text Input */}
                <div className="p-4 glass-subtle rounded-xl mb-4">
                    <label className="text-sm font-medium text-foreground block mb-2">
                        Welcome Message
                    </label>
                    <input
                        type="text"
                        value={settings.welcomeMessage}
                        onChange={e => setSettings(s => ({ ...s, welcomeMessage: e.target.value }))}
                        className="w-full h-10 px-4 rounded-xl glass-input text-sm"
                        placeholder="Enter message..."
                    />
                </div>
                
                {/* Save Button */}
                <div className="flex justify-end">
                    <button
                        onClick={handleSave}
                        disabled={saving}
                        className="px-6 py-2.5 rounded-xl bg-primary text-primary-foreground text-sm font-medium hover:bg-primary/90 transition-colors disabled:opacity-50"
                    >
                        {saving ? 'Saving...' : 'Save Settings'}
                    </button>
                </div>
            </div>
        </div>
    );
}

---

📋 Requirements Summary

Minimum Required

addons/my-addon/
└── dashboard/
    ├── config.js      # Must export { pages, navItems, apiRoutes }
    └── pages/
        └── index.jsx  # At least one page component

config.js Template

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

Page Component Template

import React from 'react';

export default function MyPage() {
    return (
        <div className="px-4 lg:px-6">
            <div className="glass-card p-6">
                <h1 className="text-xl font-bold text-foreground">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 automatically loaded from dashboard/config.js when the addon initializes.

---

💡 Tips & Best Practices

1

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

2

Handle loading states — Always show loading indicators

3

Error handling — Catch and display errors gracefully

4

API validation — Always validate request data on the backend

5

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

• Use existing Tailwind classes

• 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

---