Add admin panel, WebSocket support, and API versioning

Introduce an admin portal (React + Nginx), WebSocket routing, and
API versioning middleware with `/api/v1/` prefix deprecation.
Add master API key authentication, new Prometheus metrics for AI
token consumption and active WebSockets, and extend S3 config
with a public endpoint URL. Update test paths and fixtures to
align with the new routing structure.

integration/shaarli/config_example.env

@@ -0,0 +1,11 @@
+# Imago Hub API Connection details
+IMAGO_API_URL=http://localhost:8000/api/v1
+IMAGO_API_KEY=your-shaarli-client-api-key-here
+
+# Shaarli API credentials (if Imago needs to call back to Shaarli)
+SHAARLI_API_URL=https://bookmarks.example.com/api/v1
+SHAARLI_API_SECRET=your-shaarli-api-secret
+
+# Plugin configuration
+PLUGIN_ENABLE_AI_SUMMARIZATION=true
+PLUGIN_ENABLE_IMAGE_UPLOAD=true

integration/shaarli/example_usage.py

@@ -0,0 +1,33 @@
+import asyncio
+import os
+import logging
+from dotenv import load_dotenv
+
+from hub_plugin import ShaarliHubPlugin
+
+# Configure basic logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+
+async def main():
+    # Load environment variables
+    load_dotenv("config_example.env")
+    
+    api_url = os.getenv("IMAGO_API_URL", "http://localhost:8000/api/v1")
+    api_key = os.getenv("IMAGO_API_KEY", "your-api-key-here")
+    
+    plugin = ShaarliHubPlugin(api_url=api_url, api_key=api_key)
+    
+    print("--- Testing Imago AI Bookmark Summarization ---")
+    bookmark_url = "https://github.com/imago-project/imago"
+    
+    result = await plugin.process_bookmark(
+        url=bookmark_url, 
+        title="Imago Source Code", 
+        description="Check out this cool new project!"
+    )
+    
+    print("Result:")
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())

integration/shaarli/hub_plugin.py

@@ -0,0 +1,68 @@
+import os
+import asyncio
+import logging
+from typing import Optional, Dict, Any
+
+from imago_client import HubClient
+from imago_client.exceptions import ImagoError
+
+logger = logging.getLogger(__name__)
+
+class ShaarliHubPlugin:
+    """
+    A reference integration class demonstrating how to use the Imago SDK
+    to process incoming Shaarli bookmarks.
+    """
+    
+    def __init__(self, api_url: str, api_key: str):
+        self.api_url = api_url
+        self.api_key = api_key
+        # The HubClient manages the session and resources
+        self.client = HubClient(base_url=self.api_url, api_key=self.api_key)
+
+    async def initialize(self):
+        """Async initialization if required."""
+        pass
+        
+    async def process_bookmark(self, url: str, title: str, description: str) -> Dict[str, Any]:
+        """
+        Process a new Shaarli bookmark by analyzing the URL through Imago AI.
+        Returns suggested tags or enhanced description.
+        """
+        logger.info(f"Processing bookmark: {url}")
+        
+        try:
+            async with self.client as client:
+                # 1. Ask Immago AI to summarize the URL or draft a task
+                ai_task = await client.ai.draft_task(url=url, prompt=description or title)
+                
+                logger.info(f"Successfully processed bookmark via Imago AI. Suggested tags: {ai_task.get('suggested_tags', [])}")
+                return ai_task
+                
+        except ImagoError as e:
+            logger.error(f"Imago processing failed for bookmark {url}: {e}")
+            return {"error": str(e)}
+
+    async def upload_bookmark_screenshot(self, filepath: str) -> Optional[Dict[str, Any]]:
+        """
+        Uploads an image (screenshot) associated with a Shaarli bookmark.
+        """
+        if not os.path.exists(filepath):
+            logger.warning(f"File not found: {filepath}")
+            return None
+            
+        try:
+            async with self.client as client:
+                hub_image = await client.images.upload(filepath)
+                logger.info(f"Uploaded image to Imago hub: {hub_image.uuid}")
+                
+                # Fetch details, which might include OCR if enabled
+                details = await client.images.get(hub_image.uuid)
+                return {
+                    "uuid": details.uuid,
+                    "url": f"{self.api_url}/images/{details.uuid}/file",
+                    "ocr_text": details.ocr.text if details.ocr and details.ocr.has_text else None
+                }
+        except ImagoError as e:
+            logger.error(f"Failed to upload screenshot to Imago hub: {e}")
+            return None