superbrain-server 1.0.7 → 1.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superbrain-server",
-  "version": "1.0.7",
+  "version": "1.0.10",
   "description": "1-Line Auto-Installer and Server Execution wrapper for SuperBrain",
   "main": "index.js",
   "bin": {
@@ -22,4 +22,4 @@
     "bin/",
     "payload/"
   ]
-}
+}

package/payload/api.py

@@ -289,7 +289,15 @@ class AnalysisResponse(BaseModel):
 @app.get("/")
 async def root():
     """API information and health check (no authentication required)"""
+    
+    backend_id = "unknown"
+    backend_id_path = get_config_path("backend_id.txt")
+    if backend_id_path.exists():
+        backend_id = backend_id_path.read_text().strip()
+    
     return {
+        "backendId": backend_id,
+
         "name": "SuperBrain Instagram Analyzer API",
         "version": "1.02",
         "status": "operational",
@@ -561,12 +569,46 @@ async def analyze_instagram(request: AnalyzeRequest, token: str = Depends(verify
             logger.warning(f"⚠️  [{shortcode}] main.py stderr:\n{stderr[:1000]}")
         
         if returncode == 2:
-            retry_lines = [l.strip() for l in stdout.splitlines() if l.strip().startswith('?')]
-            retry_msg = retry_lines[-1].replace('?', '').strip() if retry_lines else "API quota exhausted or rate limited. Queued for automatic retry in 24 hours."
-            logger.info(f"? [{shortcode}] {retry_msg}")
+            # main.py detected quota exhaustion and queued item for retry.
+            # NOTE: Do NOT remove from queue here — main.py already called
+            # queue_for_retry() which set status='retry'. Removing would lose it.
+            logger.info(f"⏰ [{shortcode}] Quota exhausted — queued for automatic retry")
             raise HTTPException(
                 status_code=202,
-                detail=retry_msg
+                detail="API quota exhausted. Your request has been queued for automatic retry in 24 hours."
+            )
+        
+        if returncode != 0:
+            # Extract last meaningful error line from stdout for the error message
+            error_lines = [l.strip() for l in stdout.splitlines() if l.strip() and ('❌' in l or 'Error' in l or 'failed' in l.lower())]
+            error_detail = error_lines[-1] if error_lines else (stderr.strip()[:200] or "Analysis failed")
+            logger.error(f"❌ [{shortcode}] Analysis failed: {error_detail}")
+            logger.debug(f"[{shortcode}] stdout tail:\n{stdout[-800:]}")
+            raise HTTPException(
+                status_code=400,
+                detail=error_detail
+            )
+        
+        logger.info(f"✅ [{shortcode}] Analysis complete! Fetching from database...")
+        
+        # Get result from database — retry up to 4 times in case the SQLite write
+        # hasn't flushed yet (race condition between subprocess write and our read).
+        analysis = None
+        for _attempt in range(4):
+            analysis = db.check_cache(shortcode)
+            if analysis:
+                if _attempt > 0:
+                    logger.info(f"🔄 [{shortcode}] Found in database on retry {_attempt}")
+                break
+            if _attempt < 3:
+                logger.warning(f"⏳ [{shortcode}] Not in DB yet (attempt {_attempt+1}/4), retrying in 1s…")
+                await asyncio.sleep(1)
+        
+        if not analysis:
+            logger.error(f"❌ [{shortcode}] Not found in database after 4 attempts!")
+            raise HTTPException(
+                status_code=500,
+                detail="Analysis completed but result not found in database"
             )
         
         # Filter response

package/payload/config/backend_id.txt

@@ -0,0 +1 @@
+3f491f84-184a-40ba-9660-b882b881c4d5

package/payload/config/localtunnel.log

@@ -0,0 +1,86 @@
+
+===============================================================================
+Welcome to localhost.run!
+
+Follow your favourite reverse tunnel at [https://twitter.com/localhost_run].
+
+To set up and manage custom domains go to https://admin.localhost.run/
+
+More details on custom domains (and how to enable subdomains of your custom
+domain) at https://localhost.run/docs/custom-domains
+
+If you get a permission denied error check the faq for how to connect with a key or
+create a free tunnel without a key at [http://localhost:3000/docs/faq#generating-an-ssh-key].
+
+To explore using localhost.run visit the documentation site:
+https://localhost.run/docs/
+
+===============================================================================
+
+** your connection id is 78ac0b8b-a8f4-4185-9da5-a446d15e032f, please mention it if you send me a message about an issue. **
+
+authenticated as anonymous user
+14ebb2ac2ccab3.lhr.life tunneled with tls termination, https://14ebb2ac2ccab3.lhr.life
+create an account and add your key for a longer lasting domain name. see https://localhost.run/docs/forever-free/ for more information.
+Open your tunnel address on your mobile with this QR:
+
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+
+c3f3097e2d129a.lhr.life tunneled with tls termination, https://c3f3097e2d129a.lhr.life
+create an account and add your key for a longer lasting domain name. see https://localhost.run/docs/forever-free/ for more information.
+Open your tunnel address on your mobile with this QR:
+
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+                                                      
+

package/payload/core/model_router.py

@@ -663,6 +663,9 @@ class ModelRouter:
             try:
                 self._refresh_openrouter_models()
             except Exception as e:
+            if "429" in str(e) or "quota" in str(e).lower():
+                raise RateLimitError("Quota limit hit")
+            raise e
                 print(f"⚠️  OpenRouter auto-refresh error: {e}")
             time.sleep(OPENROUTER_FREE_CACHE_HOURS * 3600)
 
@@ -707,6 +710,9 @@ class ModelRouter:
             resp.raise_for_status()
             all_models = resp.json().get("data", [])
         except Exception as e:
+            if "429" in str(e) or "quota" in str(e).lower():
+                raise RateLimitError("Quota limit hit")
+            raise e
             print(f"⚠️  OpenRouter model discovery failed: {e}")
             return
 
@@ -1100,6 +1106,9 @@ class ModelRouter:
                 return result
 
             except Exception as e:
+            if "429" in str(e) or "quota" in str(e).lower():
+                raise RateLimitError("Quota limit hit")
+            raise e
                 status = 429 if "429" in str(e) else 0
                 self._record_failure(key, str(e), status_code=status)
                 print(f"  ✗ Failed ({type(e).__name__}), trying next …", flush=True)
@@ -1144,6 +1153,9 @@ class ModelRouter:
                 return result
 
             except Exception as e:
+            if "429" in str(e) or "quota" in str(e).lower():
+                raise RateLimitError("Quota limit hit")
+            raise e
                 status = 429 if "429" in str(e) else 0
                 self._record_failure(key, str(e), status_code=status)
                 print(f"  ✗ Failed ({type(e).__name__}), trying next …", flush=True)

package/payload/start.py

@@ -666,7 +666,7 @@ LOCALTUNNEL_ENABLED = BASE_DIR / "config" / "localtunnel_enabled.txt"
 LOCALTUNNEL_LOG = BASE_DIR / "config" / "localtunnel.log"
 
 def setup_remote_access():
-    h1("Step 6 of 7 — Remote Access (localhost.run / Port Forwarding)")
+    h1("Step 6 of 7 — Remote Access (localtunnel / Port Forwarding)")
 
     print(f"""
   The SuperBrain backend runs on {BOLD}port 5000{RESET} on your machine.
@@ -674,10 +674,10 @@ def setup_remote_access():
 
   You have two options:
 
-    {BOLD}Option A — localhost.run (easiest + free ssh tunnel){RESET}
-        localhost.run creates a public HTTPS URL seamlessly using SSH.
+    {BOLD}Option A — localtunnel (easiest + free){RESET}
+        localtunnel creates a public HTTPS URL that tunnels to your local port 5000.
         No account required.
-        Official site: {CYAN}https://localhost.run/{RESET}
+        Official site: {CYAN}https://theboroer.github.io/localtunnel-www/{RESET}
 
   {BOLD}Option B — Your own port forwarding (advanced){RESET}
     Forward {BOLD}TCP port 5000{RESET} on your router to your machine's local IP.
@@ -693,10 +693,10 @@ def setup_remote_access():
   the same network. Use your PC's local IP (e.g. 192.168.x.x) in the app.{RESET}
 """)
 
-    choice = ask_yn("Enable localhost.run on startup?", default=True)
+    choice = ask_yn("Enable localtunnel on startup?", default=True)
     if not choice:
         LOCALTUNNEL_ENABLED.unlink(missing_ok=True)
-        warn("Skipping localhost.run. Use either your own port forwarding or local WiFi.")
+        warn("Skipping localtunnel. Use either your own port forwarding or local WiFi.")
         info("Remember: set the correct server URL in the mobile app Settings.")
         return
 
@@ -711,15 +711,15 @@ def setup_remote_access():
 
     After installing, re-run {BOLD}python start.py{RESET}.
 """)
-        warn("Skipping localhost.run setup.")
+        warn("Skipping localtunnel setup.")
         return
 
     ok("npx binary found")
     LOCALTUNNEL_ENABLED.parent.mkdir(parents=True, exist_ok=True)
     LOCALTUNNEL_ENABLED.write_text("enabled")
-    ok("localhost.run auto-start enabled")
+    ok("localtunnel auto-start enabled")
     nl()
-    info("localhost.run will be started automatically every time you run start.py.")
+    info("localtunnel will be started automatically every time you run start.py.")
 
 # ══════════════════════════════════════════════════════════════════════════════
 # Step 6 — Access Token & Database
@@ -754,95 +754,83 @@ def setup_token_and_db():
 # ══════════════════════════════════════════════════════════════════════════════
 # Launch Backend
 # ══════════════════════════════════════════════════════════════════════════════
-def _extract_localhost_run_url(text: str) -> str | None:
-    """Extract first localhost.run public URL from text."""
+def _extract_localtunnel_url(text: str) -> str | None:
+    """Extract first localtunnel public URL from text."""
     import re
-    lines = text.splitlines()
-    for line in reversed(lines):
-        if "tunneled with tls termination" in line or ".lhr.life" in line or ".localhost.run" in line:
-            match = re.search(r'(https://[a-zA-Z0-9-]+\.(?:lhr\.life|localhost\.run))', line)
-            if match:
-                return match.group(1)
-    return None
+    m = re.search(r"https://[\w.-]+\.loca\.lt\b", text)
+    return m.group(0) if m else None
 
 
-def _find_localhost_run_url_from_log() -> str | None:
+def _find_localtunnel_url_from_log() -> str | None:
     """Read local tunnel log and return detected public URL if available."""
     try:
         if not LOCALTUNNEL_LOG.exists():
             return None
         text = LOCALTUNNEL_LOG.read_text(encoding="utf-8", errors="ignore")
-        return _extract_localhost_run_url(text)
+        return _extract_localtunnel_url(text)
     except Exception:
         return None
 
 
-def _stop_localhost_run_processes():
-    """Stop existing localhost.run processes so only one tunnel remains active."""
+def _stop_localtunnel_processes():
+    """Stop existing localtunnel processes so only one tunnel remains active."""
     try:
         if IS_WINDOWS:
             script = (
                 "Get-CimInstance Win32_Process "
-                "| Where-Object { $_.CommandLine -match 'nokey@localhost.run' } "
+                "| Where-Object { $_.CommandLine -match 'localtunnel|\\.loca\\.lt' } "
                 "| ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }"
             )
             subprocess.run(["powershell", "-NoProfile", "-Command", script], check=False)
         else:
-            subprocess.run(["pkill", "-f", "nokey@localhost.run"], check=False)
+            subprocess.run(["pkill", "-f", "localtunnel"], check=False)
     except Exception:
         pass
 
 
-def _start_localhost_run(port: int, timeout: int = 25) -> str | None:
-    """Start localhost.run in the background via SSH and wait for the public URL."""
+def _start_localtunnel(port: int, timeout: int = 25) -> str | None:
+    """Start localtunnel in the background and wait for the public URL."""
     import time as _time
 
-    ssh_exec = shutil.which("ssh")
-    if not ssh_exec:
-        warn("SSH is required to use localhost.run. Please install OpenSSH.")
+    npx_exec = shutil.which("npx") or shutil.which("npx.cmd")
+    if not npx_exec:
         return None
 
-    # Clean stale ssh tunnel processes.
-    _stop_localhost_run_processes()
+    # Clean stale localtunnel processes.
+    _stop_localtunnel_processes()
     _time.sleep(0.8)
 
-    info("Starting localhost.run SSH tunnel in background …")
+    info("Starting localtunnel in background …")
     try:
         LOCALTUNNEL_LOG.parent.mkdir(parents=True, exist_ok=True)
         LOCALTUNNEL_LOG.write_text("")
 
         log_handle = open(LOCALTUNNEL_LOG, "a", encoding="utf-8", buffering=1)
         kwargs = {
+            "start_new_session": True,
             "stdout": log_handle,
             "stderr": subprocess.STDOUT,
-            "stdin": subprocess.DEVNULL,
             "text": True,
         }
-        if IS_WINDOWS:
-            kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
-        
-        cmd = [ssh_exec, "-o", "StrictHostKeyChecking=no", "-R", f"80:localhost:{port}", "nokey@localhost.run"]
-        process = subprocess.Popen(cmd, **kwargs)
-        
-        _time.sleep(1.0)
-        if process.poll() is not None:
-            warn(f"Could not start localhost.run, exited with {process.returncode}")
-            return None
-
+        if IS_WINDOWS and npx_exec.lower().endswith(".cmd"):
+            cmd = ["cmd", "/c", npx_exec, "-y", "localtunnel", "--port", str(port)]
+        else:
+            cmd = [npx_exec, "-y", "localtunnel", "--port", str(port)]
+        subprocess.Popen(cmd, **kwargs)
     except Exception as e:
-        warn(f"Could not start localhost.run: {e}")
+        warn(f"Could not start localtunnel: {e}")
         return None
 
     # Poll log output until URL is emitted.
     deadline = _time.time() + timeout
     while _time.time() < deadline:
         _time.sleep(1)
-        url = _find_localhost_run_url_from_log()
+        url = _find_localtunnel_url_from_log()
         if url:
-            ok(f"localhost.run active  →  {GREEN}{BOLD}{url}{RESET}")
+            ok(f"localtunnel active  →  {GREEN}{BOLD}{url}{RESET}")
             return url
 
-    warn("localhost.run started but URL is not available yet.")
+    warn("localtunnel started but URL is not available yet.")
     info(f"Check tunnel logs in: {LOCALTUNNEL_LOG}")
     return None
 
@@ -1214,26 +1202,26 @@ def launch_backend():
     token = TOKEN_FILE.read_text().strip() if TOKEN_FILE.exists() else "—"
     local_ip = _detect_local_ip()
 
-    localhost_run_enabled = bool(shutil.which("ssh"))
+    localtunnel_enabled = bool(shutil.which("npx") or shutil.which("npx.cmd"))
 
-    localhost_run_url: str | None = None
-    if localhost_run_enabled:
-        localhost_run_url = _start_localhost_run(PORT)
+    localtunnel_url: str | None = None
+    if localtunnel_enabled:
+        localtunnel_url = _start_localtunnel(PORT)
     else:
-        localhost_run_url = _find_localhost_run_url_from_log()
+        localtunnel_url = _find_localtunnel_url_from_log()
 
-    if localhost_run_url:
-        tunnel_line = f"    Public URL   →  {GREEN}{BOLD}{localhost_run_url}{RESET}  {DIM}(localhost.run){RESET}"
-        tunnel_hint = f"         · public     →  {GREEN}{localhost_run_url}{RESET}"
-    elif localhost_run_enabled:
+    if localtunnel_url:
+        tunnel_line = f"    Public URL   →  {GREEN}{BOLD}{localtunnel_url}{RESET}  {DIM}(localtunnel){RESET}"
+        tunnel_hint = f"         · public     →  {GREEN}{localtunnel_url}{RESET}"
+    elif localtunnel_enabled:
         tunnel_line = f"    Public URL   →  {YELLOW}(starting — URL pending, check localtunnel.log){RESET}"
-        tunnel_hint = f"         · public     →  run:  {DIM}ssh -R 80:localhost:{PORT} nokey@localhost.run{RESET}"
+        tunnel_hint = f"         · public     →  run:  {DIM}npx localtunnel --port {PORT}{RESET}"
     else:
         tunnel_line = ""
-        tunnel_hint = f"         · public     →  install OpenSSH first, then run: {DIM}ssh -R 80:localhost:{PORT} nokey@localhost.run{RESET}"
+        tunnel_hint = f"         · public     →  install Node.js first, then run: {DIM}npx localtunnel --port {PORT}{RESET}"
 
     # ── Generate and display QR code ──────────────────────────────────────────
-    qr_url = localhost_run_url if localhost_run_url else f"http://{local_ip}:{PORT}"
+    qr_url = localtunnel_url if localtunnel_url else f"http://{local_ip}:{PORT}"
     _display_connect_qr(qr_url, token)
 
     print(f"""
@@ -1294,7 +1282,7 @@ def launch_backend_status():
             url = match.group(1)
             
     if url == "NOT_FOUND":
-        warn("Could not find a running localhost.run URL in config/localtunnel.log.")
+        warn("Could not find a running localtunnel URL in config/localtunnel.log.")
         nl()
         print("  Wait 5 seconds, or run 'superbrain-server' to start the server.")
         return
@@ -1306,11 +1294,11 @@ def launch_backend_status():
     network_url = f"http://{local_ip}:5000"
     
     nl()
-    print(f"    Local URL      ?  {CYAN}{local_url}{RESET}")
-    print(f"    Network URL    ?  {CYAN}{network_url}{RESET}")
-    print(f"    Public URL   ?  {CYAN}{url}{RESET}  (localtunnel)")
-    print(f"    API docs       ?  {CYAN}{local_url}/docs{RESET}")
-    print(f"    Access Token   ?  {BOLD}{MAGENTA}{token}{RESET}")
+    print(f"    Local URL      \u2192  {CYAN}{local_url}{RESET}")
+    print(f"    Network URL    \u2192  {CYAN}{network_url}{RESET}")
+    print(f"    Public URL   \u2192  {CYAN}{url}{RESET}  (localtunnel)")
+    print(f"    API docs       \u2192  {CYAN}{local_url}/docs{RESET}")
+    print(f"    Access Token   \u2192  {BOLD}{MAGENTA}{token}{RESET}")
     nl()
 
 def main():
@@ -1339,7 +1327,7 @@ def main():
     3 · Configure AI provider keys + Instagram credentials
     4 · Set up an offline AI model via Ollama  (qwen3-vl:4b)
     5 · Set up offline audio transcription     (Whisper + ffmpeg)
-    6 · Configure remote access (localhost.run or port forwarding)
+    6 · Configure remote access (localtunnel or port forwarding)
     7 · Generate Access Token & initialise database
 
   Press {BOLD}Enter{RESET} to accept defaults shown in [{DIM}brackets{RESET}].

package/payload/test_backend.py

@@ -0,0 +1,241 @@
+"""
+SuperBrain - Comprehensive Backend Test Suite
+Tests all API endpoints against the running backend.
+"""
+import requests
+import sys
+import json
+import time
+
+# Config
+BASE_URL = "http://localhost:5000"
+TOKEN = "4XVTLWWV"
+HEADERS = {"X-API-Key": TOKEN, "Content-Type": "application/json"}
+
+TEST_YT_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
+
+passed = 0
+failed = 0
+skipped = 0
+
+def test(name, condition, detail=""):
+    global passed, failed
+    if condition:
+        passed += 1
+        print(f"  [PASS] {name}")
+    else:
+        failed += 1
+        print(f"  [FAIL] {name} -- {detail}")
+
+def skip(name, reason):
+    global skipped
+    skipped += 1
+    print(f"  [SKIP] {name} -- {reason}")
+
+# Phase 1: Health & Auth
+print("\n--- Phase 1: Health & Auth ---")
+
+try:
+    r = requests.get(f"{BASE_URL}/status", timeout=5)
+    test("1.1 GET /status", r.status_code == 200 and r.json().get("status") == "online", f"status={r.status_code}")
+except Exception as e:
+    test("1.1 GET /status", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/health", headers=HEADERS, timeout=5)
+    data = r.json()
+    test("1.2 GET /health (auth)", r.status_code == 200 and "database" in data, f"status={r.status_code}")
+except Exception as e:
+    test("1.2 GET /health", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/health", headers={"X-API-Key": "WRONGTKN"}, timeout=5)
+    test("1.3 Auth rejection (wrong)", r.status_code == 401, f"status={r.status_code}")
+except Exception as e:
+    test("1.3 Auth rejection", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/health", timeout=5)
+    test("1.4 Auth rejection (none)", r.status_code in [401, 403, 422], f"status={r.status_code}")
+except Exception as e:
+    test("1.4 Auth rejection (none)", False, str(e))
+
+# Phase 2: Read Endpoints
+print("\n--- Phase 2: Read Endpoints ---")
+
+try:
+    r = requests.get(f"{BASE_URL}/recent?limit=10", headers=HEADERS, timeout=10)
+    data = r.json()
+    test("2.1 GET /recent", r.status_code == 200 and "data" in data, f"status={r.status_code}")
+    print(f"       found {len(data.get('data', []))} posts")
+except Exception as e:
+    test("2.1 GET /recent", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/categories", headers=HEADERS, timeout=10)
+    data = r.json()
+    test("2.2 GET /categories", r.status_code == 200 and "categories" in data, f"status={r.status_code}")
+    print(f"       found {len(data.get('categories', []))} categories")
+except Exception as e:
+    test("2.2 GET /categories", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/queue-status", headers=HEADERS, timeout=10)
+    data = r.json()
+    test("2.3 GET /queue-status", r.status_code == 200 and "processing_count" in data, f"keys={list(data.keys())}")
+    print(f"       processing={data.get('processing_count',0)}, queue={data.get('queue_count',0)}, retry={data.get('retry_count',0)}")
+except Exception as e:
+    test("2.3 GET /queue-status", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/stats", headers=HEADERS, timeout=10)
+    test("2.4 GET /stats", r.status_code == 200, f"status={r.status_code}")
+except Exception as e:
+    test("2.4 GET /stats", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/search?tags=travel&limit=5", headers=HEADERS, timeout=10)
+    test("2.5 GET /search?tags=travel", r.status_code == 200, f"status={r.status_code}")
+except Exception as e:
+    test("2.5 GET /search", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/queue/retry", headers=HEADERS, timeout=10)
+    test("2.6 GET /queue/retry", r.status_code == 200, f"status={r.status_code}")
+except Exception as e:
+    test("2.6 GET /queue/retry", False, str(e))
+
+# Phase 3: Collections CRUD
+print("\n--- Phase 3: Collections CRUD ---")
+
+test_collection_id = None
+
+try:
+    r = requests.get(f"{BASE_URL}/collections", headers=HEADERS, timeout=10)
+    data = r.json()
+    test("3.1 GET /collections", r.status_code == 200, f"status={r.status_code}")
+    print(f"       found {len(data)} collections")
+except Exception as e:
+    test("3.1 GET /collections", False, str(e))
+
+try:
+    r = requests.post(f"{BASE_URL}/collections", headers=HEADERS, json={"id": "test-id", "name": "Test Collection", "icon": "test"}, timeout=10)
+    data = r.json()
+    test("3.2 POST /collections (create)", r.status_code == 200 and data.get("id"), f"status={r.status_code}")
+    test_collection_id = data.get("id")
+    print(f"       created ID: {test_collection_id}")
+except Exception as e:
+    test("3.2 POST /collections", False, str(e))
+
+if test_collection_id:
+    try:
+        r = requests.post(f"{BASE_URL}/collections", headers=HEADERS, json={"id": test_collection_id, "name": "Updated Test", "icon": "ok"}, timeout=10)
+        test("3.3 POST /collections (update)", r.status_code == 200, f"status={r.status_code}")
+    except Exception as e:
+        test("3.3 POST /collections (update)", False, str(e))
+
+    try:
+        r = requests.delete(f"{BASE_URL}/collections/{test_collection_id}", headers=HEADERS, timeout=10)
+        test("3.4 DELETE /collections", r.status_code == 200, f"status={r.status_code}")
+    except Exception as e:
+        test("3.4 DELETE /collections", False, str(e))
+else:
+    skip("3.3 PUT /collections", "no collection created")
+    skip("3.4 DELETE /collections", "no collection created")
+
+try:
+    r = requests.get(f"{BASE_URL}/collections", headers=HEADERS, timeout=10)
+    data = r.json()
+    collections = data.get("data", [])
+    wl = next((c for c in collections if c.get("name") == "Watch Later"), None)
+    if wl:
+        r = requests.delete(f"{BASE_URL}/collections/{wl['id']}", headers=HEADERS, timeout=10)
+        test("3.5 Watch Later protection", r.status_code in [400, 403], f"status={r.status_code} (should be blocked)")
+    else:
+        skip("3.5 Watch Later protection", "no Watch Later found")
+except Exception as e:
+    test("3.5 Watch Later protection", False, str(e))
+
+# Phase 4: Settings
+print("\n--- Phase 4: Settings ---")
+
+try:
+    r = requests.get(f"{BASE_URL}/settings/ai-providers", headers=HEADERS, timeout=10)
+    test("4.1 GET /settings/ai-providers", r.status_code == 200, f"status={r.status_code}")
+except Exception as e:
+    test("4.1 GET /settings/ai-providers", False, str(e))
+
+try:
+    r = requests.post(f"{BASE_URL}/settings/ai-providers", headers=HEADERS,
+                       json={"provider": "groq", "api_key": "gsk_test"}, timeout=10)
+    test("4.2 POST ai-providers (Groq)", r.status_code == 200, f"status={r.status_code}")
+except Exception as e:
+    test("4.2 POST ai-providers", False, str(e))
+
+try:
+    r = requests.get(f"{BASE_URL}/settings/instagram", headers=HEADERS, timeout=10)
+    test("4.3 GET /settings/instagram", r.status_code == 200, f"status={r.status_code}")
+except Exception as e:
+    test("4.3 GET /settings/instagram", False, str(e))
+
+try:
+    r = requests.post(f"{BASE_URL}/settings/instagram", headers=HEADERS,
+                       json={"username": "testuser", "password": "testpass"}, timeout=10)
+    test("4.4 POST /settings/instagram", r.status_code == 200, f"status={r.status_code}")
+except Exception as e:
+    test("4.4 POST /settings/instagram", False, str(e))
+
+# Phase 5: Export/Import
+print("\n--- Phase 5: Export/Import ---")
+
+try:
+    r = requests.get(f"{BASE_URL}/export", headers=HEADERS, timeout=15)
+    test("5.1 GET /export", r.status_code == 200, f"status={r.status_code}")
+    ed = r.json()
+    print(f"       exported {len(ed.get('posts', []))} posts, {len(ed.get('collections', []))} collections")
+except Exception as e:
+    test("5.1 GET /export", False, str(e))
+
+try:
+    r = requests.post(f"{BASE_URL}/import", headers=HEADERS,
+                       json={"posts": [], "collections": [], "mode": "merge"}, timeout=15)
+    test("5.2 POST /import (merge, empty)", r.status_code == 200, f"status={r.status_code}")
+except Exception as e:
+    test("5.2 POST /import", False, str(e))
+
+# Phase 6: Analysis
+print("\n--- Phase 6: Analysis (YouTube) ---")
+
+try:
+    print("       submitting YouTube URL... (timeout 90s)")
+    r = requests.post(f"{BASE_URL}/analyze", headers=HEADERS,
+                       json={"url": TEST_YT_URL}, timeout=90)
+    data = r.json()
+    if r.status_code == 200:
+        test("6.1 POST /analyze (YouTube)", data.get("success") == True, f"success={data.get('success')}")
+        if data.get("data"):
+            d = data["data"]
+            print(f"       title: {d.get('title', 'N/A')[:60]}")
+            print(f"       category: {d.get('category', 'N/A')}")
+            print(f"       tags: {str(d.get('tags', [])[:5])}")
+            print(f"       cached: {data.get('cached', False)}")
+    elif r.status_code == 202:
+        skip("6.1 POST /analyze (YouTube)", "queued for retry (quota)")
+    elif r.status_code == 503:
+        skip("6.1 POST /analyze (YouTube)", "503 server busy")
+    else:
+        test("6.1 POST /analyze (YouTube)", False, f"status={r.status_code}")
+except requests.exceptions.Timeout:
+    skip("6.1 POST /analyze (YouTube)", "timed out (90s)")
+except Exception as e:
+    test("6.1 POST /analyze (YouTube)", False, str(e))
+
+# Summary
+print("\n" + "=" * 50)
+print(f"  PASSED: {passed}")
+print(f"  FAILED: {failed}")
+print(f"  SKIPPED: {skipped}")
+print(f"  TOTAL: {passed + failed + skipped}")
+print("=" * 50)
+
+sys.exit(1 if failed > 0 else 0)

package/payload/tests/test_api.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python3
+import requests
+import json
+
+# Read token
+with open('token.txt', 'r') as f:
+    token = f.read().strip()
+
+# Test the /recent endpoint
+response = requests.get(
+    'http://localhost:5000/recent?limit=10',
+    headers={'X-API-Key': token}
+)
+
+print(f"Status Code: {response.status_code}")
+print(f"\nResponse:")
+print(json.dumps(response.json(), indent=2))

package/payload/tests/test_db.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+import sys
+from pathlib import Path
+
+# Ensure backend root is in sys.path
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from core.database import get_db
+
+db = get_db()
+posts = db.get_recent(5)
+print(f'Found {len(posts)} posts in database')
+print()
+
+for p in posts:
+    print(f"Shortcode: {p.get('shortcode', 'N/A')}")
+    print(f"Title: {p.get('title', 'N/A')}")
+    print(f"Username: {p.get('username', 'N/A')}")
+    print(f"URL: {p.get('url', 'N/A')}")
+    print(f"Category: {p.get('category', 'N/A')}")
+    print(f"Analyzed: {p.get('analyzed_at', 'N/A')}")
+    print("-" * 60)

package/payload/tests/test_sync_code.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Legacy filename retained for compatibility.
+This script now validates API key authentication behavior.
+"""
+
+import sys
+from pathlib import Path
+
+from fastapi.testclient import TestClient
+
+# Ensure backend root is in sys.path
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from api import app, API_TOKEN, generate_api_token  # noqa: E402
+
+
+client = TestClient(app)
+
+
+def test_generate_api_token_shape():
+    token = generate_api_token()
+    assert isinstance(token, str)
+    assert len(token) == 8
+    assert token.isalnum()
+
+
+def test_ping_works_without_auth():
+    response = client.get('/ping')
+    assert response.status_code == 200
+
+
+def test_queue_status_rejects_invalid_api_key():
+    response = client.get('/queue-status', headers={'X-API-Key': 'INVALID_TOKEN'})
+    assert response.status_code == 401
+
+
+def test_queue_status_accepts_valid_api_key():
+    response = client.get('/queue-status', headers={'X-API-Key': API_TOKEN})
+    assert response.status_code == 200
+
+
+def test_connect_endpoint_is_deprecated():
+    response = client.post('/connect', json={'api_key': API_TOKEN})
+    assert response.status_code == 410
+
+
+if __name__ == '__main__':
+    print('Running API key auth tests...')
+    test_generate_api_token_shape()
+    print('PASS: API token generation shape')
+
+    test_ping_works_without_auth()
+    print('PASS: /ping unauthenticated access')
+
+    test_queue_status_rejects_invalid_api_key()
+    print('PASS: /queue-status rejects invalid API key')
+
+    test_queue_status_accepts_valid_api_key()
+    print('PASS: /queue-status accepts valid API key')
+
+    test_connect_endpoint_is_deprecated()
+    print('PASS: /connect deprecated behavior')
+
+    print('\nAll API key auth tests passed!')

package/payload/fix.py

@@ -1,66 +0,0 @@
-import sys, shutil
-path1 = 'D:/superbrain/backend/start.py'
-path2 = 'D:/superbrain/superbrain-cli/payload/start.py'
-
-status_code = '''
-def launch_backend_status():
-    h1("SuperBrain Server Status")
-    PORT = 5000
-    token = TOKEN_FILE.read_text().strip() if TOKEN_FILE.exists() else "�"
-    local_ip = _detect_local_ip()
-
-    localtunnel_enabled = bool(shutil.which("npx") or shutil.which("npx.cmd"))
-    localtunnel_url: str | None = None
-    if localtunnel_enabled:
-        localtunnel_url = _find_localtunnel_url_from_log()
-
-    if localtunnel_url:
-        tunnel_line = f"    Public URL   ?  {GREEN}{BOLD}{localtunnel_url}{RESET}  {DIM}(localtunnel){RESET}"
-        tunnel_hint = f"         � public     ?  {GREEN}{localtunnel_url}{RESET}"
-    elif localtunnel_enabled:
-        tunnel_line = f"    Public URL   ?  {YELLOW}(running � URL in localtunnel.log){RESET}"
-        tunnel_hint = f"         � public     ?  run:  {DIM}npx localtunnel --port {PORT}{RESET}"
-    else:
-        tunnel_line = ""
-        tunnel_hint = f"         � public     ?  install Node.js first, then run: {DIM}npx localtunnel --port {PORT}{RESET}"
-
-    qr_url = localtunnel_url if localtunnel_url else f"http://{local_ip}:{PORT}"
-    _display_connect_qr(qr_url, token)
-
-    print(f\"\"\"
-    {GREEN}{BOLD}Server Status{RESET}
-
-    Local URL      ?  {CYAN}http://127.0.0.1:{PORT}{RESET}
-    Network URL    ?  {CYAN}http://{local_ip}:{PORT}{RESET}
-{(tunnel_line + chr(10)) if tunnel_line else ''}    API docs       ?  {CYAN}http://127.0.0.1:{PORT}/docs{RESET}
-    Access Token   ?  {BOLD}{MAGENTA}{token}{RESET}
-
-  {YELLOW}Mobile app setup:{RESET}
-    {BOLD}Option A � Scan QR code:{RESET}
-      1. Open the app  ?  Settings  ?  tap the {BOLD}QR icon{RESET} ??
-      2. Scan the QR code shown above
-
-    {BOLD}Option B � Manual setup:{RESET}
-      1. Go to app  ?  ? settings
-      2. Set {BOLD}Server URL{RESET} to:
-{tunnel_hint}
-           � Same WiFi  ?  http://{local_ip}:{PORT}
-      3. Set {BOLD}Access Token{RESET} to: {BOLD}{MAGENTA}{token}{RESET}
-\"\"\")
-    sys.exit(0)
-
-'''
-
-for path in [path1, path2]:
-    with open(path, 'r', encoding='utf-8') as f:
-        content = f.read()
-
-    if 'def launch_backend_status()' not in content:
-        content = content.replace('def main():', status_code + 'def main():')
-
-    if 'status_mode = "--status" in sys.argv' not in content:
-        content = content.replace('    reset_mode = "--reset" in sys.argv', '    status_mode = "--status" in sys.argv\\n    if status_mode:\\n        launch_backend_status()\\n        return\\n\\n    reset_mode = "--reset" in sys.argv')
-
-    with open(path, 'w', encoding='utf-8') as f:
-        f.write(content)
-print("Done fixing start.py!")

package/payload/fix2.py

@@ -1,63 +0,0 @@
-import sys, shutil
-path1 = 'D:/superbrain/backend/start.py'
-path2 = 'D:/superbrain/superbrain-cli/payload/start.py'
-
-status_code = '''
-def launch_backend_status():
-    h1("SuperBrain Server Status")
-    PORT = 5000
-    token = TOKEN_FILE.read_text().strip() if TOKEN_FILE.exists() else "�"
-    local_ip = _detect_local_ip()
-
-    localtunnel_enabled = bool(shutil.which("npx") or shutil.which("npx.cmd"))
-    localtunnel_url: str | None = None
-    if localtunnel_enabled:
-        localtunnel_url = _find_localtunnel_url_from_log()
-
-    if localtunnel_url:
-        tunnel_line = f"    Public URL   ?  {GREEN}{BOLD}{localtunnel_url}{RESET}  {DIM}(localtunnel){RESET}"
-        tunnel_hint = f"         � public     ?  {GREEN}{localtunnel_url}{RESET}"
-    elif localtunnel_enabled:
-        tunnel_line = f"    Public URL   ?  {YELLOW}(running � URL in localtunnel.log){RESET}"
-        tunnel_hint = f"         � public     ?  run:  {DIM}npx localtunnel --port {PORT}{RESET}"
-    else:
-        tunnel_line = ""
-        tunnel_hint = f"         � public     ?  install Node.js first, then run: {DIM}npx localtunnel --port {PORT}{RESET}"
-
-    qr_url = localtunnel_url if localtunnel_url else f"http://{local_ip}:{PORT}"
-    _display_connect_qr(qr_url, token)
-
-    print(f\"\"\"
-    {GREEN}{BOLD}Server Status{RESET}
-
-    Local URL      ?  {CYAN}http://127.0.0.1:{PORT}{RESET}
-    Network URL    ?  {CYAN}http://{local_ip}:{PORT}{RESET}
-{(tunnel_line + chr(10)) if tunnel_line else ''}    API docs       ?  {CYAN}http://127.0.0.1:{PORT}/docs{RESET}
-    Access Token   ?  {BOLD}{MAGENTA}{token}{RESET}
-
-  {YELLOW}Mobile app setup:{RESET}
-    {BOLD}Option A � Scan QR code:{RESET}
-      1. Open the app  ?  Settings  ?  tap the {BOLD}QR icon{RESET} ??
-      2. Scan the QR code shown above
-
-    {BOLD}Option B � Manual setup:{RESET}
-      1. Go to app  ?  ? settings
-      2. Set {BOLD}Server URL{RESET} to:
-{tunnel_hint}
-           � Same WiFi  ?  http://{local_ip}:{PORT}
-      3. Set {BOLD}Access Token{RESET} to: {BOLD}{MAGENTA}{token}{RESET}
-\"\"\")
-    sys.exit(0)
-
-'''
-
-for path in [path1, path2]:
-    with open(path, 'r', encoding='utf-8') as f:
-        content = f.read()
-
-    if 'def launch_backend_status()' not in content:
-        content = content.replace('def main():', status_code + 'def main():')
-
-    with open(path, 'w', encoding='utf-8') as f:
-        f.write(content)
-print("Done fixing start.py again!")