EyeBOT is a Discord bot built with TypeScript and discord.js v14, designed to integrate Albion Online player data with Discord servers. It provides character registration, verification, automatic nickname synchronization, and comprehensive health monitoring for production deployments.

• Character Registration: Link Discord accounts to Albion Online characters
• Character Verification: Secure verification system via in-game mail
• Automatic Nickname Sync: Discord nicknames update to match Albion character names
• Multi-Character Support: Users can register multiple Albion characters
• Bulk Updates: Admin command to update all registered members at once
• Health Monitoring: Built-in system monitoring with heartbeat functionality
• Database Migrations: Version-controlled database schema management
• Modular Architecture: Feature-based organization for easy expansion

Before installing EyeBOT, ensure you have:

• Node.js v16 or higher (Download)
• npm (comes with Node.js)
• MySQL v5.7 or higher (Download)
• Discord Bot Token (Create a bot)
• Git (optional, for cloning)

git clone https://github.com/DBcide/EyeBOT.git
cd EyeBOT

npm install

Create a .env file in the project root:

# Copy the example below and fill in your values

# ================================
# Discord Configuration
# ================================
# Your Discord bot token (from https://discord.com/developers/applications)
DISCORD_TOKEN=your_discord_bot_token_here

# Your Discord application client ID
CLIENT_ID=your_client_id_here

# (Optional) Your Discord guild/server ID for testing
GUILD_ID=your_guild_id_here

# ================================
# Database Configuration
# ================================
# MySQL database host
DB_HOST=localhost

# MySQL username
DB_USER=root

# MySQL password (leave empty if no password)
DB_PASSWORD=your_password_here

# Database name (will be created during setup)
DB_NAME=eyebot

# MySQL port (default: 3306)
DB_PORT=3306

# ================================
# Health Monitoring (Optional)
# ================================
# How often to collect system metrics (milliseconds)
HEALTH_MONITOR_INTERVAL_MS=10000

# How often to send heartbeat requests (milliseconds)
HEARTBEAT_INTERVAL_MS=60000

# URL to send heartbeat POST requests (prevents host shutdown)
HEARTBEAT_URL=https://your-monitoring-endpoint.com/heartbeat

Where to find these values:

Create the database in MySQL:

CREATE DATABASE eyebot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Or use the MySQL command line:

mysql -u root -p -e "CREATE DATABASE eyebot CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

npm run migrate

This will create all necessary tables:

• migrations - Migration tracking
• tracer_users - Albion character registrations

npm run register

This registers all slash commands with Discord's API.

npm run build

Development Mode (with auto-reload):

npm run dev

Production Mode:

npm start

With PM2 (recommended for production):

pm2 start ecosystem.config.js

npm run dev          # Run bot with ts-node (development)
npm run watch        # Compile TypeScript in watch mode
npm run build        # Compile TypeScript to dist/
npm run clean        # Clean dist/ directory

npm start            # Run compiled bot from dist/

npm run migrate              # Run all pending migrations
npm run migrate:rollback     # Rollback last migration
npm run migrate:list         # List executed migrations

npm run register     # Register slash commands with Discord API

EyeBOT includes a comprehensive health monitoring system designed to prevent shutdown by hosting providers that terminate idle processes (e.g., O2Switch).

System Metrics:

• CPU usage (%)
• Memory usage (total, used, percentage)
• Heap memory (Node.js)
• Process uptime
• System load averages

Discord Metrics:

• Number of guilds
• Total users across all guilds
• Channel count
• WebSocket ping (latency)
• Connection status

When HEARTBEAT_URL is configured, the bot sends periodic POST requests with the following JSON payload:

{
  "timestamp": "2025-01-05T10:30:00.000Z",
  "status": "healthy",
  "uptime": 3600,
  "memory": {
    "percentage": "45.23",
    "used": "512.00 MB"
  },
  "cpu": {
    "usage": "12.50"
  },
  "discord": {
    "guilds": 5,
    "users": 1250,
    "ping": 45,
    "status": "READY"
  }
}

Headers sent:

Content-Type: application/json
User-Agent: EyeBOT-HealthMonitor/1.0

1. Set environment variables:

   HEARTBEAT_URL=https://your-endpoint.com/heartbeat
   HEARTBEAT_INTERVAL_MS=60000  # Send every 60 seconds

2. Use with monitoring services:

   • UptimeRobot: Create HTTP monitor pointing to your endpoint
   • Pingdom: Set up transaction check
   • Custom server: Create endpoint that receives POST requests

3. Example Node.js heartbeat receiver:

   app.post('/heartbeat', (req, res) => {
     console.log('Heartbeat received:', req.body);
     // Store metrics, trigger alerts, etc.
     res.status(200).send('OK');
   });

Metrics are logged every 10 seconds (configurable):

📊 Health | CPU: 12.34% | RAM: 45.67% | Heap: 89.12 MB/256.00 MB | Uptime: 1h 23m 45s | Guilds: 5 | Users: 1250 | Ping: 45ms

Alerts are triggered when:

• CPU usage > 80%
• Memory usage > 80%

EyeBOT/
├── src/
│   ├── core/                    # Core bot framework
│   │   ├── Bot.ts              # Main bot orchestrator
│   │   ├── BaseCommand.ts      # Abstract command class
│   │   └── BaseEvent.ts        # Abstract event class
│   │
│   ├── features/               # Feature modules
│   │   └── tracer/            # Albion character tracking
│   │       ├── commands/      # Slash commands
│   │       ├── models/        # TypeScript interfaces
│   │       ├── services/      # Business logic
│   │       └── utils/         # Utilities
│   │
│   ├── shared/                # Shared services
│   │   └── services/
│   │       ├── DatabaseService.ts        # MySQL wrapper
│   │       ├── LoggerService.ts          # Logging
│   │       ├── HealthMonitorService.ts   # Health monitoring
│   │       └── ServiceContainer.ts       # DI container
│   │
│   ├── database/              # Database layer
│   │   ├── migrations/        # Schema migrations
│   │   ├── Migration.ts       # Migration interface
│   │   └── MigrationService.ts
│   │
│   ├── scripts/               # Utility scripts
│   │   ├── register-commands.ts
│   │   ├── run-migrations.ts
│   │   ├── rollback-migration.ts
│   │   └── list-migrations.ts
│   │
│   └── index.ts               # Entry point
│
├── dist/                      # Compiled JavaScript (generated)
├── .env                       # Environment variables (not in git)
├── package.json
├── tsconfig.json
└── README.md                  # This file

Stores Albion Online character registrations.

1. Create src/features/<feature>/commands/MyCommand.ts:

   import { BaseCommand } from '../../../core/BaseCommand';
   import { ChatInputCommandInteraction, SlashCommandBuilder } from 'discord.js';
   
   export default class MyCommand extends BaseCommand {
       public name = 'mycommand';
       public description = 'My command description';
   
       public buildCommand(): SlashCommandBuilder {
           return new SlashCommandBuilder()
               .setName(this.name)
               .setDescription(this.description);
       }
   
       public async execute(interaction: ChatInputCommandInteraction): Promise<void> {
           await interaction.reply('Hello!');
       }
   }

2. Build and register:

   npm run build
   npm run register

1. Create src/database/migrations/YYYYMMDD_HHMMSS_description.ts:

   import { Migration } from '../Migration';
   import mysql from 'mysql2/promise';
   
   export const migration: Migration = {
       name: '20250105_120000_add_new_table',
   
       async up(connection: mysql.PoolConnection): Promise<void> {
           await connection.query(`
               CREATE TABLE my_table (
                   id INT AUTO_INCREMENT PRIMARY KEY,
                   name VARCHAR(255) NOT NULL
               );
           `);
       },
   
       async down(connection: mysql.PoolConnection): Promise<void> {
           await connection.query('DROP TABLE my_table');
       }
   };

2. Export in src/database/migrations/index.ts

3. Run: npm run migrate

1. Install PM2 globally:

   npm install -g pm2

2. Create ecosystem.config.js:

   module.exports = {
     apps: [{
       name: 'eyebot',
       script: './dist/index.js',
       instances: 1,
       autorestart: true,
       watch: false,
       max_memory_restart: '1G',
       env: {
         NODE_ENV: 'production'
       }
     }]
   };

3. Start:

   pm2 start ecosystem.config.js

4. Useful PM2 commands:

   pm2 status           # Check status
   pm2 logs eyebot      # View logs
   pm2 restart eyebot   # Restart bot
   pm2 stop eyebot      # Stop bot
   pm2 delete eyebot    # Remove from PM2

For O2Switch Node.js hosting:

1. Enable health monitoring in .env:

   HEARTBEAT_URL=https://your-domain.com/heartbeat
   HEARTBEAT_INTERVAL_MS=60000

2. Use PM2 to keep the bot running

3. The heartbeat will prevent the host from shutting down idle processes

1. Check bot is online in Discord
2. Verify slash commands are registered: npm run register
3. Check bot has proper permissions in your server
4. Review logs for errors

1. Verify MySQL is running: mysql --version
2. Check .env credentials are correct
3. Ensure database exists: SHOW DATABASES;
4. Test connection: npm run migrate:list

1. Re-register commands: npm run register
2. Wait up to 1 hour for global commands to propagate
3. Use GUILD_ID in .env for instant testing (guild-specific commands)

1. Check HEARTBEAT_URL is set in .env
2. Verify endpoint is accessible: curl -X POST <HEARTBEAT_URL>
3. Check logs for heartbeat errors
4. Ensure firewall allows outbound HTTP requests

The bot implements automatic rate limiting for the Albion Online API:

• Batch processing: /updateall processes 5 users at a time
• Delays: 1 second between batches to avoid 429 errors
• Error handling: Graceful degradation on API failures

Public Project

• Author: DBcide (Olivier Français)
• Contact: contact@dbcide.fr
• Commercial use prohibited without authorization
• Modification and redistribution prohibited without authorization
• Attribution required for any authorized use
• See LICENSE.txt for full details

For issues, questions, or feature requests:

1. Check existing documentation (README.md)
2. Review troubleshooting section above
3. Contact: contact@dbcide.fr

• discord.js - Discord API wrapper
• Albion Online - Game data API
• O2Switch - Node.js hosting platform