# ModpackChecker — Pterodactyl Blueprint Extension

**Version:** 1.0.0  
**Author:** Firefrost Gaming / Frostystyle  
**License:** Commercial License - Unauthorized redistribution, resale, or sharing of this source code is strictly prohibited.

A Pterodactyl Panel extension that checks modpack versions across CurseForge, Modrinth, FTB, and Technic platforms. Shows update status on the dashboard and provides manual version checks from the server console.

---

## Table of Contents

1. [Features](#features)
2. [Architecture Overview](#architecture-overview)
3. [File Structure](#file-structure)
4. [Installation](#installation)
5. [Configuration](#configuration)
6. [Usage](#usage)
7. [Development](#development)
8. [API Reference](#api-reference)
9. [Troubleshooting](#troubleshooting)
10. [Support](#support)

---

## Features

### Dashboard Badge
- Shows a colored dot next to each server name on the dashboard
- **🟠 Orange (Fire #FF6B35):** Update available
- **🟢 Teal (Frost #4ECDC4):** Up to date
- Hover for version details tooltip
- Single API call per page load (cached with 60s TTL)

### Console Widget
- "Check for Updates" button on each server's console page
- Real-time version check against platform API
- Rate limited: 2 checks per minute per server
- Shows modpack name and latest version

### Admin Panel
- Configure CurseForge API key
- View supported platforms
- PRO features: Discord notifications, custom check intervals

### Supported Platforms
| Platform | ID Type | API Key Required | Status |
|----------|---------|------------------|--------|
| CurseForge | Numeric project ID | ✅ Yes | ✅ Working |
| Modrinth | Project ID or slug | ❌ No | ✅ Working |
| FTB | Numeric modpack ID | ❌ No | ✅ Working |
| Technic | URL slug | ❌ No | ✅ Working |

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           MODPACK VERSION CHECKER                            │
└─────────────────────────────────────────────────────────────────────────────┘

                    ┌─────────────────────────────────────┐
                    │     CRON JOB (runs every 4-6 hrs)   │
                    │     php artisan modpackchecker:check │
                    └──────────────────┬──────────────────┘
                                       │
                                       ▼
                    ┌─────────────────────────────────────┐
                    │         DATABASE CACHE              │
                    │     modpackchecker_servers table    │
                    │                                     │
                    │  • server_uuid                      │
                    │  • platform, modpack_id             │
                    │  • current_version, latest_version  │
                    │  • status (string)                  │
                    │  • last_checked timestamp           │
                    └──────────────────┬──────────────────┘
                                       │
                    ┌──────────────────┴──────────────────┐
                    │                                     │
                    ▼                                     ▼
    ┌───────────────────────────┐       ┌───────────────────────────┐
    │    DASHBOARD BADGE        │       │    CONSOLE WIDGET         │
    │    (UpdateBadge.tsx)      │       │    (wrapper.tsx)          │
    │                           │       │                           │
    │  • Reads from cache ONLY  │       │  • Manual "Check" button  │
    │  • 60-second TTL          │       │  • LIVE API call          │
    │  • Shows 🟠 or 🟢 dot     │       │  • Rate limited (2/min)   │
    └───────────────────────────┘       └───────────────────────────┘
```

---

## File Structure

```
blueprint-extension/
├── README.md
├── CHANGELOG.md
├── conf.yml
├── build.sh
├── icon.png
│
├── app/
│   ├── Console/Commands/
│   │   └── CheckModpackUpdates.php
│   ├── Http/Controllers/
│   │   └── ModpackAPIController.php
│   └── Services/
│       └── ModpackApiService.php
│
├── admin/
│   ├── controller.php
│   └── view.blade.php
│
├── database/migrations/
│   └── 2026_04_06_000000_create_modpackchecker_servers_table.php
│
├── routes/
│   └── client.php
│
└── views/
    ├── server/wrapper.tsx
    └── dashboard/UpdateBadge.tsx
```

---

## Installation

### Prerequisites

- Pterodactyl Panel v1.11+
- Blueprint Framework (beta-2026-01 or newer)
- PHP 8.1+
- Node.js 18+
- Yarn package manager

### Standard Installation (BuiltByBit)

1. Upload the downloaded `modpackchecker.blueprint` file to your Pterodactyl panel's root directory (usually `/var/www/pterodactyl`).

2. Run the Blueprint installation command:
   ```bash
   blueprint -install modpackchecker
   ```

3. The framework will automatically inject the frontend components and rebuild the panel assets.

4. Set up the cron job for automated checks:
   ```bash
   # Add to crontab
   0 */6 * * * www-data cd /var/www/pterodactyl && php artisan modpackchecker:check >> /dev/null 2>&1
   ```

### Developer/Manual Installation

If installing from raw source:
```bash
cp -r blueprint-extension /var/www/pterodactyl/.blueprint/extensions/modpackchecker
chown -R www-data:www-data /var/www/pterodactyl/.blueprint/extensions/modpackchecker
blueprint -build
```

---

## Configuration

### Server Egg Variables

For modpack detection, set these variables in your server's egg:

| Variable | Description | Example |
|----------|-------------|---------|
| `MODPACK_PLATFORM` | Platform name | `modrinth`, `curseforge`, `ftb`, `technic` |
| `MODPACK_ID` | Platform-specific ID | `adrenaserver` (Modrinth slug) |
| `MODPACK_CURRENT_VERSION` | Installed version | `1.7.0` |

### CurseForge API Key

CurseForge requires an API key:

1. Apply for API access at https://console.curseforge.com/
2. Go to **Admin Panel → Extensions → ModpackChecker**
3. Enter your API key and save

---

## Usage

### Dashboard Badge
Badges appear automatically for servers that:
- Have `MODPACK_PLATFORM` egg variable set
- Have been checked by the cron job at least once

### Manual Check
1. Go to any server's console page
2. Click "Check for Updates" button
3. View results showing modpack name and version status

### Cron Command
Run manually for testing:
```bash
php artisan modpackchecker:check
```

---

## Development

### Adding a New Platform

1. Open `app/Services/ModpackApiService.php`
2. Add your new platform check method (e.g., `private function checkNewPlatform(string $id): array`)
3. Add the platform key to the `match()` statement inside the `fetchLatestVersion()` method
4. The Controller and Cron Command will automatically inherit the new logic
5. Update this README to reflect the newly supported platform

### Testing API Endpoints
```bash
# Manual check (requires auth token)
curl -X POST "https://panel.example.com/api/client/extensions/modpackchecker/servers/{uuid}/check" \
  -H "Authorization: Bearer {token}"

# Get all statuses
curl "https://panel.example.com/api/client/extensions/modpackchecker/status" \
  -H "Authorization: Bearer {token}"
```

---

## API Reference

### POST `/api/client/extensions/modpackchecker/servers/{server}/check`

Manual version check for a specific server. Triggers a live API call to the modpack platform.

**Rate Limit:** 2 requests per minute per server

**Response:**
```json
{
    "success": true,
    "platform": "modrinth",
    "modpack_id": "adrenaserver",
    "modpack_name": "Adrenaserver",
    "latest_version": "1.7.0+1.21.1.fabric",
    "status": "checked"
}
```

### GET `/api/client/extensions/modpackchecker/status`

Get cached status for all servers accessible to the authenticated user.

**Response:**
```json
{
    "a1b2c3d4-...": {
        "update_available": true,
        "modpack_name": "All The Mods 9",
        "current_version": "0.2.51",
        "latest_version": "0.2.60"
    }
}
```

---

## Troubleshooting

### Badge not showing
1. Check server has `MODPACK_PLATFORM` variable set
2. Run cron command manually: `php artisan modpackchecker:check`
3. Check `modpackchecker_servers` table for entries

### "CurseForge API key not configured"
1. Go to Admin → Extensions → ModpackChecker
2. Enter your CurseForge API key
3. Key must have mod read permissions

### 500 errors on check
1. Check PHP error log: `tail -f /var/log/php8.3-fpm.log`
2. Verify controller namespace: `Pterodactyl\Http\Controllers`
3. Restart PHP-FPM: `systemctl restart php8.3-fpm`

### "Rate limit reached" message
The manual check is limited to 2 requests per minute per server. Wait 60 seconds and try again.

---

## Support

**Need help?** Join our Discord for support:
- **Discord:** [discord.firefrostgaming.com](https://discord.firefrostgaming.com)
- **Email:** dev@firefrostgaming.com
- **Website:** [firefrostgaming.com](https://firefrostgaming.com)

---

## Credits

**Developed by:** Firefrost Gaming / Frostystyle  
**Architecture Review:** Gemini AI

**Part of Firefrost Gaming**  
*Fire + Frost + Foundation = Where Love Builds Legacy* 🔥❄️💙