# Shaarli Integration

The **Imago Hub** can be integrated directly with **Shaarli** (the PHP-based bookmark manager) to automatically process and enhance your bookmarks when you save them.

## Overview

When you save a new bookmark in Shaarli, you might want to:
1. Automatically fetch the URL and summarize the page content using AI
2. Generate tags automatically based on the page content
3. Archive full-page screenshots to Imago for offline reading

This repository includes a reference implementation for this architecture using the Imago Python SDK.

## Components

The `integration/shaarli/` directory contains:
- `hub_plugin.py` — A Python class (`ShaarliHubPlugin`) that acts as a middleware interacting with the `imago-client` SDK.
- `config_example.env` — Example environment variable file for the plugin layer.
- `example_usage.py` — A standalone script demonstrating how the plugin summarizes URLs.

## Setup Instructions

1. **Install the SDK:** The script requires the Imago Python SDK.
   ```bash
   cd sdk
   pip install imago-client
   ```

2. **Configure Environment variables:**
   Copy `integration/shaarli/config_example.env` to `.env` and fill it with your **Imago Admin API Key** or a specific Client API Key provisioned with `ai:use` and `images:write` scopes.

3. **Deploy as a microservice or hook:**
   Since Shaarli is written in PHP, to hook python scripts into Shaarli you have a few options:
   
   - **Option A (WebHook):** Deploy a small FastAPI/Flask wrapper around `hub_plugin.py` and configure Shaarli's WebHook plugin to POST data to your wrapper whenever a new link is created.
   - **Option B (Cron/Background Job):** Have a Python daemon watch the Shaarli RSS/Atom feed or poll its REST API, grab new entries, process them via `hub_plugin.py`, and PATCH the bookmark back in Shaarli with the newly generated Description and Tags using the Shaarli REST API.

## Example Flow (Option B)

1. You save `https://github.com/imago-project/imago` to Shaarli.
2. The Python daemon detects the new bookmark via Shaarli's API.
3. The daemon calls `plugin.process_bookmark(url)`.
4. Imago leverages OpenRouter/Gemini to fetch and summarize the GitHub page.
5. Imago returns `{"title": "...", "description": "...", "suggested_tags": ["github", "python", "ai"]}`.
6. The daemon PATCHes the Shaarli API to enrich the bookmark.