feat: integrate FlareSolverr for Cloudflare bypass on clone sources

- Add FLARESOLVERR_URL env var to .env.example
- Update fetchSourceFurnidata to fall back to FlareSolverr on CF challenges (403/HTML)
- Add docker-compose.yml with FlareSolverr service
- Add scripts/health-check.sh for FlareSolverr readiness check
- Add health:check script to package.json
- Document FlareSolverr setup in README

.env.example

@@ -71,3 +71,6 @@ PAYPAL_API=https://api-m.sandbox.paypal.com
 
 # --- LOGGING ---
 LOG_LEVEL=error
+
+# --- FLARESOLVERR (Cloudflare bypass for clone sources) ---
+FLARESOLVERR_URL=http://localhost:8191

README.md

@@ -514,6 +514,26 @@ Supports Cloudflare Turnstile and Google reCAPTCHA. Configure via CMS Settings.
 
 Optional OpenAI-powered moderation for comments and guestbook posts. Set `OPENAI_API_KEY`.
 
+### FlareSolverr (Cloudflare Bypass)
+
+Some clone sources (e.g. Leet, Hubbly, Habblet City) are protected by Cloudflare and return challenge pages instead of JSON. FlareSolverr acts as a proxy that solves these challenges automatically.
+
+**Setup:**
+
+```bash
+docker compose up -d flaresolverr
+```
+
+Set the URL in `.env`:
+
+```
+FLARESOLVERR_URL=http://localhost:8191
+```
+
+When a source URL returns a 403 or HTML (CF challenge), the clone import automatically falls back to FlareSolverr. If FlareSolverr is not running or is unreachable, the source is skipped with a warning.
+
+See `docker-compose.yml` for the FlareSolverr service definition.
+
 ---
 
 ## Development

docker-compose.yml

@@ -0,0 +1,11 @@
+version: "3.8"
+
+services:
+  flaresolverr:
+    image: flaresolverr/flaresolverr:latest
+    container_name: flaresolverr
+    ports:
+      - "8191:8191"
+    restart: unless-stopped
+    environment:
+      - LOG_LEVEL=info

package.json

@@ -24,6 +24,7 @@
 		"db:studio": "drizzle-kit studio",
 		"db:introspect": "drizzle-kit introspect",
 		"jobs:worker": "tsx scripts/jobs-worker.ts",
+		"health:check": "bash scripts/health-check.sh",
 		"prepare": "husky"
 	},
 	"lint-staged": {

scripts/health-check.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+URL="${FLARESOLVERR_URL:-http://localhost:8191}"
+MAX_RETRIES="${FLARESOLVERR_MAX_RETRIES:-30}"
+RETRY_INTERVAL="${FLARESOLVERR_RETRY_INTERVAL:-2}"
+
+echo "Waiting for FlareSolverr at ${URL}..."
+
+for i in $(seq 1 "$MAX_RETRIES"); do
+	if curl -sf "${URL}/health" >/dev/null 2>&1; then
+		echo "FlareSolverr is healthy."
+		exit 0
+	fi
+	echo "Attempt ${i}/${MAX_RETRIES} - FlareSolverr not ready, retrying in ${RETRY_INTERVAL}s..."
+	sleep "$RETRY_INTERVAL"
+done
+
+echo "ERROR: FlareSolverr did not become healthy after ${MAX_RETRIES} attempts."
+exit 1

src/lib/services/clone-import.ts

@@ -5,6 +5,7 @@ import { db, ItemsBase } from "@/lib/db";
 import { logger } from "@/lib/logger";
 import { extractFurniIconPng } from "@/lib/services/clone-icon";
 import type { CloneSource } from "@/lib/services/clone-sources";
+import { fetchWithFlareSolver } from "@/lib/services/flare-solver";
 import { getFurniAssetDirs } from "@/lib/services/furni-asset-dirs";
 import { appendFurniEntry } from "@/lib/services/furni-data";
 import {
@@ -88,14 +89,26 @@ export async function fetchSourceFurnidata(
 ): Promise<SourceFurni[]> {
 	const hit = cache.get(url);
 	if (hit && now && now - hit.ts < TTL) return hit.list;
-	const res = await fetch(url, {
-		signal: AbortSignal.timeout(30000),
-		headers: browserHeaders(),
-	});
-	if (!res.ok) throw new Error(`furnidata fetch failed: ${res.status} ${url}`);
+	let body: string;
+	try {
+		const res = await fetch(url, {
+			signal: AbortSignal.timeout(30000),
+			headers: browserHeaders(),
+		});
+		if (
+			res.ok &&
+			res.headers.get("content-type")?.includes("application/json")
+		) {
+			body = await res.text();
+		} else {
+			body = await fetchWithFlareSolver(url);
+		}
+	} catch {
+		body = await fetchWithFlareSolver(url);
+	}
 	let list: SourceFurni[];
 	try {
-		const json = await res.json();
+		const json = JSON.parse(body);
 		list = parseFurnidata(json);
 	} catch (err) {
 		throw new Error(

src/lib/services/flare-solver.ts

@@ -0,0 +1,51 @@
+const FLARESOLVERR_URL =
+	process.env.FLARESOLVERR_URL ?? "http://localhost:8191";
+
+export async function fetchWithFlareSolver(
+	url: string,
+	timeout = 30000,
+): Promise<string> {
+	const res = await fetch(FLARESOLVERR_URL, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			cmd: "request.get",
+			url,
+			maxTimeout: timeout,
+		}),
+		signal: AbortSignal.timeout(timeout + 5000),
+	});
+
+	if (!res.ok) {
+		throw new Error(
+			`FlareSolverr request failed: ${res.status} ${res.statusText}`,
+		);
+	}
+
+	const data = (await res.json()) as {
+		solution?: { response: string };
+		error?: string;
+	};
+
+	if (data.error) {
+		throw new Error(`FlareSolverr error: ${data.error}`);
+	}
+
+	if (!data.solution) {
+		throw new Error("FlareSolverr: no solution in response");
+	}
+
+	return data.solution.response;
+}
+
+export async function fetchJsonWithFlareSolver<T = unknown>(
+	url: string,
+	timeout = 30000,
+): Promise<T> {
+	const body = await fetchWithFlareSolver(url, timeout);
+	try {
+		return JSON.parse(body) as T;
+	} catch {
+		throw new Error(`flare-solver: could not parse JSON from ${url}`);
+	}
+}