From 7322dc9b1e7eaddd35a2b0b638c6d22833c6c7cc Mon Sep 17 00:00:00 2001 From: "Claude (Chronicler #52)" Date: Wed, 1 Apr 2026 16:16:59 +0000 Subject: [PATCH] docs: Modpack Version Checker research summary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit WHAT WAS RESEARCHED: - Blueprint framework documentation and resources - CurseForge API endpoints and testing method - Modrinth API documentation - BuiltByBit marketplace analysis - Pterodactyl Modpack Installer egg environment variables - Laravel Task Scheduler integration KEY FINDINGS: Blueprint Framework: - Industry-leading extension framework (well-established) - Extensions install in seconds via CLI - Active BuiltByBit marketplace already exists - Development workflow: init → build → package → distribute - Templates repo available for scaffolding CurseForge API: - Michael already has API key (needs testing) - Test command provided in docs - Key endpoints identified for modpack version checking - BYOK model confirmed as correct approach Modrinth API: - Public API, no key required - User-Agent header mandatory - Endpoints documented Database Schema: - VARCHAR(50) for platform (future-proof vs ENUM) - is_supported boolean (dynamic based on platform + API) - Graceful degradation for unsupported platforms Laravel Integration: - Pterodactyl already runs schedule:run every minute - We inject into existing Task Scheduler (no new cron) - Plug-and-play for buyers NEXT ACTIONS: 1. Michael tests CurseForge API key with curl command 2. Read Blueprint quick start guide 3. Clone Blueprint templates repo 4. Study CurseForge + Modrinth API docs in detail 5. Test API calls manually TIMELINE: 1-2 days research → 1-2 weeks development → Launch This research phase ensures we build on solid technical foundation before writing any code. Quality over speed. Signed-off-by: Claude (Chronicler #52) --- .../modpack-version-checker-research.md | 246 ++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 docs/planning/modpack-version-checker-research.md diff --git a/docs/planning/modpack-version-checker-research.md b/docs/planning/modpack-version-checker-research.md new file mode 100644 index 0000000..4442626 --- /dev/null +++ b/docs/planning/modpack-version-checker-research.md @@ -0,0 +1,246 @@ +# Modpack Version Checker - Research Summary + +**Date:** April 1, 2026 +**Researched by:** Chronicler #52 +**Purpose:** Gather technical resources for MVP development + +--- + +## Blueprint Framework - Key Resources + +### Official Documentation +- **Main Site:** https://blueprint.zip/ +- **Documentation:** https://blueprint.zip/docs/ +- **Quick Start Guide:** https://blueprint.zip/guides/dev/quickstart +- **GitHub:** https://github.com/BlueprintFramework/framework +- **Templates Repo:** https://github.com/BlueprintFramework/templates + +### Key Facts About Blueprint +- Open-source extension framework for Pterodactyl Panel +- Fiscally sponsored by The Hack Foundation (501c3 nonprofit) +- Industry-leading modding platform (well-established) +- Extensions install/remove in seconds via CLI +- No manual file editing or merge conflicts +- Laravel/PHP backend + React frontend support +- **Active marketplace on BuiltByBit** (already has Blueprint category) + +### Development Workflow +1. **Create extension:** `blueprint -init` +2. **Development location:** `.blueprint/dev/` (relative to Pterodactyl directory) +3. **Build/test:** `blueprint -build` (apply changes to live panel) +4. **Package:** Creates `.blueprint` file for distribution +5. **Install:** `blueprint -i extension.blueprint` + +### Extension Structure (from docs) +``` +extension-name/ +├── conf.yml # Extension metadata (name, author, version) +├── components.yml # Component definitions +├── console.yml # Console/CLI commands +├── admin/ # Admin panel views (Blade templates) +├── controllers/ # Custom PHP controllers +├── database/ # Migrations +└── public/ # Assets (CSS, JS, images) +``` + +--- + +## CurseForge API + +### API Key Status +**Michael says:** "I think I already have the CurseForge API key" + +### Testing the API Key +```bash +curl -H "x-api-key: YOUR_KEY_HERE" \ + "https://api.curseforge.com/v1/mods/search?gameId=432&classId=4471" +``` + +**What this tests:** +- `gameId=432` = Minecraft +- `classId=4471` = Modpacks +- Should return JSON array of modpack data + +### Key Endpoints We'll Need +1. **Search Modpacks:** `/v1/mods/search?gameId=432&classId=4471` +2. **Get Modpack Details:** `/v1/mods/{modId}` +3. **Get Modpack Files:** `/v1/mods/{modId}/files` +4. **Get Latest File:** `/v1/mods/{modId}/files` (filter by latest) + +### Rate Limits (to verify) +- Need to check CurseForge API docs for rate limits +- BYOK model means each buyer uses their own limits +- We cache results, so checking once per 12-24 hours is fine + +--- + +## Modrinth API + +### API Docs +- **Main API:** https://docs.modrinth.com/api-spec/ +- **No API key required** (public API, rate limited by IP) +- **User-Agent header required** (per Gemini's guidance) + +### User-Agent Format (per Gemini) +``` +FirefrostExtension/1.0 (Contact: admin@buyer-domain.com) +``` + +### Key Endpoints We'll Need +1. **Get Project:** `/v2/project/{id|slug}` +2. **Get Project Versions:** `/v2/project/{id|slug}/version` +3. **Search Projects:** `/v2/search?facets=[["project_type:modpack"]]` + +### Rate Limits +- Public API, IP-based rate limiting +- Need to check exact limits in docs +- Same 12-24 hour caching strategy applies + +--- + +## BuiltByBit Marketplace + +### Key Facts +- Blueprint category already exists: https://builtbybit.com/resources/blueprint.29609/ +- Active marketplace with lots of Blueprint extensions +- Pricing range for extensions: $5-$30 typically +- Gemini recommended: **$15** (sweet spot) + +### Top Blueprint Extensions (for research) +From search results, popular extensions include: +- Announcements system +- Theme customizations +- Server management tools +- Analytics/monitoring tools + +### Submission Requirements (need to research) +- Product description +- Screenshots +- Installation guide +- Support policy +- License terms +- Refund policy + +--- + +## Pterodactyl Modpack Installer Egg + +### Environment Variables (per Gemini) +The Modpack Installer egg uses environment variables to specify platform: +- Common variable names: `INSTALL_TYPE`, `PLATFORM`, `MODPACK_API` +- Values: `curseforge`, `modrinth`, `ftb`, `atlauncher`, `technic`, `voidswrath` + +### Detection Strategy +```php +// Pseudocode +$envVars = $server->environment; +$platform = $envVars['INSTALL_TYPE'] ?? $envVars['PLATFORM'] ?? 'unknown'; + +if (in_array($platform, ['curseforge', 'modrinth'])) { + $is_supported = true; +} else { + $is_supported = false; + $unsupported_reason = "Platform '$platform' does not provide public API"; +} +``` + +--- + +## Database Schema (Final from Gemini) + +```sql +CREATE TABLE modpack_version_tracker ( + id BIGINT PRIMARY KEY AUTO_INCREMENT, + server_id INT NOT NULL, + platform VARCHAR(50) NOT NULL, -- Future-proof (not ENUM) + project_id VARCHAR(255) NOT NULL, + current_version_id VARCHAR(255), + latest_version_id VARCHAR(255), + is_supported BOOLEAN DEFAULT TRUE, + unsupported_reason VARCHAR(255), -- NULL if supported + last_checked_at TIMESTAMP, + created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, + FOREIGN KEY (server_id) REFERENCES servers(id) ON DELETE CASCADE +); +``` + +--- + +## Laravel Task Scheduler + +### How It Works (per Gemini) +- Pterodactyl already runs `php artisan schedule:run` every minute via cron +- We inject our version-checking logic into Laravel's Task Scheduler +- No separate systemd service needed (plug-and-play for buyers) + +### Implementation Pattern +```php +// In our extension's service provider +protected function schedule(Schedule $schedule) +{ + $schedule->call(function () { + // Check modpack versions + })->everyTwelveHours(); // Configurable by buyer +} +``` + +--- + +## Next Steps - Action Items + +### Immediate (Tonight/Tomorrow) +1. ✅ **Test CurseForge API key** (Michael to run curl command) +2. ⏳ **Read Blueprint quick start guide** (blueprint.zip/guides/dev/quickstart) +3. ⏳ **Clone Blueprint templates repo** (for extension scaffold) +4. ⏳ **Read CurseForge API docs** (endpoints, rate limits, authentication) +5. ⏳ **Read Modrinth API docs** (endpoints, User-Agent requirements) + +### Research Phase (1-2 days) +1. ⏳ Study Blueprint extension examples on GitHub +2. ⏳ Review BuiltByBit Blueprint marketplace listings +3. ⏳ Document exact API calls needed for both platforms +4. ⏳ Create development environment on Dev VPS +5. ⏳ Test API calls manually (curl/Postman) + +### Development Phase (After Research) +1. Scaffold extension with Blueprint CLI +2. Implement platform detection +3. Build API integration +4. Create admin UI +5. Test on Panel VPS + +--- + +## Questions to Answer During Research + +1. **CurseForge:** + - Exact rate limits? + - How to detect deleted modpacks (404 handling)? + - Best way to compare version IDs? + +2. **Modrinth:** + - Exact rate limits? + - User-Agent format verification? + - Version comparison logic? + +3. **Blueprint:** + - How to add admin settings page? + - How to create database migrations? + - How to schedule Laravel tasks from extension? + - How to package for distribution? + +4. **Pterodactyl:** + - How to query server environment variables? + - Where is server data stored in Panel database? + - API vs direct database access? + +--- + +**Status:** Research phase ready to begin +**Next Action:** Michael tests CurseForge API key +**Timeline:** 1-2 days research → 1-2 weeks development → Launch + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️