feat: add Telegram notification system with granular event toggles

Add notifications crate shared between API and indexer to send Telegram
messages on scan/thumbnail/conversion completion/failure, metadata linking,
batch and refresh events. Configurable via a new Notifications tab in the
backoffice settings with per-event toggle switches grouped by category.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

apps/api/Cargo.toml

@@ -15,6 +15,7 @@ futures = "0.3"
 image.workspace = true
 jpeg-decoder.workspace = true
 lru.workspace = true
+notifications = { path = "../../crates/notifications" }
 stripstream-core = { path = "../../crates/core" }
 parsers = { path = "../../crates/parsers" }
 rand.workspace = true

apps/api/Dockerfile

@@ -6,13 +6,15 @@ COPY Cargo.toml ./
 COPY apps/api/Cargo.toml apps/api/Cargo.toml
 COPY apps/indexer/Cargo.toml apps/indexer/Cargo.toml
 COPY crates/core/Cargo.toml crates/core/Cargo.toml
+COPY crates/notifications/Cargo.toml crates/notifications/Cargo.toml
 COPY crates/parsers/Cargo.toml crates/parsers/Cargo.toml
 
-RUN mkdir -p apps/api/src apps/indexer/src crates/core/src crates/parsers/src && \
+RUN mkdir -p apps/api/src apps/indexer/src crates/core/src crates/notifications/src crates/parsers/src && \
     echo "fn main() {}" > apps/api/src/main.rs && \
     echo "fn main() {}" > apps/indexer/src/main.rs && \
     echo "" > apps/indexer/src/lib.rs && \
     echo "" > crates/core/src/lib.rs && \
+    echo "" > crates/notifications/src/lib.rs && \
     echo "" > crates/parsers/src/lib.rs
 
 # Build dependencies only (cached as long as Cargo.toml files don't change)
@@ -26,12 +28,13 @@ RUN --mount=type=cache,target=/usr/local/cargo/registry \
 COPY apps/api/src apps/api/src
 COPY apps/indexer/src apps/indexer/src
 COPY crates/core/src crates/core/src
+COPY crates/notifications/src crates/notifications/src
 COPY crates/parsers/src crates/parsers/src
 
 RUN --mount=type=cache,target=/usr/local/cargo/registry \
     --mount=type=cache,target=/usr/local/cargo/git \
     --mount=type=cache,target=/app/target \
-    touch apps/api/src/main.rs crates/core/src/lib.rs crates/parsers/src/lib.rs && \
+    touch apps/api/src/main.rs crates/core/src/lib.rs crates/notifications/src/lib.rs crates/parsers/src/lib.rs && \
     cargo build --release -p api && \
     cp /app/target/release/api /usr/local/bin/api
 

apps/api/src/main.rs

@@ -21,6 +21,7 @@ mod series;
 mod settings;
 mod state;
 mod stats;
+mod telegram;
 mod thumbnails;
 mod tokens;
 
@@ -111,6 +112,7 @@ async fn main() -> anyhow::Result<()> {
         .route("/prowlarr/test", get(prowlarr::test_prowlarr))
         .route("/qbittorrent/add", axum::routing::post(qbittorrent::add_torrent))
         .route("/qbittorrent/test", get(qbittorrent::test_qbittorrent))
+        .route("/telegram/test", get(telegram::test_telegram))
         .route("/komga/sync", axum::routing::post(komga::sync_komga_read_books))
         .route("/komga/reports", get(komga::list_sync_reports))
         .route("/komga/reports/:id", get(komga::get_sync_report))

apps/api/src/metadata.rs

@@ -369,6 +369,16 @@ pub async fn approve_metadata(
             .await?;
     }
 
+    // Notify via Telegram
+    let provider_for_notif: String = row.get("provider");
+    notifications::notify(
+        state.pool.clone(),
+        notifications::NotificationEvent::MetadataApproved {
+            series_name: series_name.clone(),
+            provider: provider_for_notif,
+        },
+    );
+
     Ok(Json(ApproveResponse {
         status: "approved".to_string(),
         report,

apps/api/src/metadata_batch.rs

@@ -124,6 +124,12 @@ pub async fn start_batch(
 
     // Spawn the background processing task
     let pool = state.pool.clone();
+    let library_name: Option<String> = sqlx::query_scalar("SELECT name FROM libraries WHERE id = $1")
+        .bind(library_id)
+        .fetch_optional(&state.pool)
+        .await
+        .ok()
+        .flatten();
     tokio::spawn(async move {
         if let Err(e) = process_metadata_batch(&pool, job_id, library_id).await {
             warn!("[METADATA_BATCH] job {job_id} failed: {e}");
@@ -134,6 +140,13 @@ pub async fn start_batch(
             .bind(e.to_string())
             .execute(&pool)
             .await;
+            notifications::notify(
+                pool.clone(),
+                notifications::NotificationEvent::MetadataBatchFailed {
+                    library_name,
+                    error: e.to_string(),
+                },
+            );
         }
     });
 
@@ -621,6 +634,21 @@ async fn process_metadata_batch(
 
     info!("[METADATA_BATCH] job={job_id} completed: {processed}/{total} series processed");
 
+    let library_name: Option<String> = sqlx::query_scalar("SELECT name FROM libraries WHERE id = $1")
+        .bind(library_id)
+        .fetch_optional(pool)
+        .await
+        .ok()
+        .flatten();
+    notifications::notify(
+        pool.clone(),
+        notifications::NotificationEvent::MetadataBatchCompleted {
+            library_name,
+            total_series: total,
+            processed,
+        },
+    );
+
     Ok(())
 }
 

apps/api/src/metadata_refresh.rs

@@ -133,6 +133,12 @@ pub async fn start_refresh(
 
     // Spawn the background processing task
     let pool = state.pool.clone();
+    let library_name: Option<String> = sqlx::query_scalar("SELECT name FROM libraries WHERE id = $1")
+        .bind(library_id)
+        .fetch_optional(&state.pool)
+        .await
+        .ok()
+        .flatten();
     tokio::spawn(async move {
         if let Err(e) = process_metadata_refresh(&pool, job_id, library_id).await {
             warn!("[METADATA_REFRESH] job {job_id} failed: {e}");
@@ -143,6 +149,13 @@ pub async fn start_refresh(
             .bind(e.to_string())
             .execute(&pool)
             .await;
+            notifications::notify(
+                pool.clone(),
+                notifications::NotificationEvent::MetadataRefreshFailed {
+                    library_name,
+                    error: e.to_string(),
+                },
+            );
         }
     });
 
@@ -319,6 +332,22 @@ async fn process_metadata_refresh(
 
     info!("[METADATA_REFRESH] job={job_id} completed: {refreshed} updated, {unchanged} unchanged, {errors} errors");
 
+    let library_name: Option<String> = sqlx::query_scalar("SELECT name FROM libraries WHERE id = $1")
+        .bind(library_id)
+        .fetch_optional(pool)
+        .await
+        .ok()
+        .flatten();
+    notifications::notify(
+        pool.clone(),
+        notifications::NotificationEvent::MetadataRefreshCompleted {
+            library_name,
+            refreshed,
+            unchanged,
+            errors,
+        },
+    );
+
     Ok(())
 }
 

apps/api/src/telegram.rs

@@ -0,0 +1,46 @@
+use axum::{extract::State, Json};
+use serde::Serialize;
+use utoipa::ToSchema;
+
+use crate::{error::ApiError, state::AppState};
+
+#[derive(Serialize, ToSchema)]
+pub struct TelegramTestResponse {
+    pub success: bool,
+    pub message: String,
+}
+
+/// Test Telegram connection by sending a test message
+#[utoipa::path(
+    get,
+    path = "/telegram/test",
+    tag = "notifications",
+    responses(
+        (status = 200, body = TelegramTestResponse),
+        (status = 400, description = "Telegram not configured"),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("Bearer" = []))
+)]
+pub async fn test_telegram(
+    State(state): State<AppState>,
+) -> Result<Json<TelegramTestResponse>, ApiError> {
+    let config = notifications::load_telegram_config(&state.pool)
+        .await
+        .ok_or_else(|| {
+            ApiError::bad_request(
+                "Telegram is not configured or disabled. Set bot_token, chat_id, and enable it.",
+            )
+        })?;
+
+    match notifications::send_test_message(&config).await {
+        Ok(()) => Ok(Json(TelegramTestResponse {
+            success: true,
+            message: "Test message sent successfully".to_string(),
+        })),
+        Err(e) => Ok(Json(TelegramTestResponse {
+            success: false,
+            message: format!("Failed to send: {e}"),
+        })),
+    }
+}