fix(email): email tracking fixes, analytics endpoints, SDK regen, settings validation (#57)

* fix(email): detect Gmail image proxy in user agent parsing

Google proxies all email images through googleusercontent.com servers,
sending a UA like "Mozilla/5.0 ... Firefox/11.0 (via ggpht.com
GoogleImageProxy)". The parseUserAgent function now checks for
GoogleImageProxy/ggpht.com before browser detection, displaying
"Gmail (Google Proxy)" instead of incorrectly showing "Firefox".

* fix(email): show empty state for headers tab when no custom headers

* fix(email): navigate back to Sent Emails tab from email detail

* feat(email): add global tracking stats and events endpoints

Add /emails/events/stats and /emails/events endpoints to the
temps-email plugin so the Analytics tab works. Previously these
routes were only in the unregistered temps-email-tracking plugin.

- GET /emails/events/stats: aggregated open/click/bounce stats
- GET /emails/events: paginated list of all tracking events
- Fix event type aliases in EmailAnalytics component

* fix(email): add email_id to TrackingEventResponse to fix analytics crash

* feat(sdk): regenerate Node SDK with email tracking types

- Add OpenAPI annotations to global events endpoints
- Regenerate Node SDK from latest OpenAPI spec
- New types: TrackingEventResponse, TrackedLinkResponse,
  EmailTrackingResponse, tracked_html_body, track_opens, track_clicks
- New SDK functions: getEmailTracking, getEmailEvents, getEmailLinks,
  trackOpen, trackClick

* fix(settings): validate external URL on client and server

Server: reject external URLs that don't start with http(s)://, contain
# or ? characters, or aren't parseable. Sanitize by trimming whitespace
and trailing slashes.

Client: add react-hook-form validation with the same rules, show inline
error messages, and surface server validation errors in toast.

* docs(changelog): add email tracking fixes and SDK regen

Author: dviejokfs

CHANGELOG.md

@@ -9,7 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - **Email tracking analytics UI**: event timeline on email detail page showing individual open/click/bounce/delivery events with IP, user-agent, and metadata; new Analytics tab with delivery rate cards and global event log
-- **Global email events endpoint**: `GET /emails/events` lists tracking events across all emails with optional `email_id` and `event_type` filters
+- **Global email events endpoint**: `GET /emails/events` lists tracking events across all emails with optional `email_id` and `event_type` filters; `GET /emails/events/stats` returns aggregated open/click/bounce rates
+- **Node SDK regenerated**: includes `tracked_html_body`, `track_opens`, `track_clicks`, `TrackingEventResponse`, `TrackedLinkResponse`, `EmailTrackingResponse` types and SDK functions
 - **Multi-preset detection**: `detect_all_presets_from_files` returns all matching presets per directory (e.g., Dockerfile + Next.js + Docker Compose in the same root), letting users choose their preferred deployment method instead of silently picking the highest-priority match
 - **Database pool configuration**: env vars `TEMPS_DB_MAX_CONNECTIONS` (default 100), `TEMPS_DB_MIN_CONNECTIONS` (default 1), `TEMPS_DB_ACQUIRE_TIMEOUT` (default 30s), and `TEMPS_DB_IDLE_TIMEOUT` (default 600s) for tuning the SQLx connection pool on resource-constrained servers
 - **Enter-submit in wizards**: `useEnterSubmit` hook added to Domain, DNS Provider, Domain Creation, and Import wizards — pressing Enter advances to the next step or submits on the final step
@@ -28,6 +29,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 - Email event timeline returned 404: UI fetched from `/emails/{id}/events` (unregistered plugin route) instead of `/emails/{id}/tracking/events`; also fixed event type mismatches (`open`/`click` vs `opened`/`clicked`) and added client-side pagination for flat array response
+- Gmail image proxy misidentified as "Firefox" in email tracking events; now shows "Gmail (Google Proxy)"
+- Email detail back button navigated to default Providers tab instead of Sent Emails tab
+- Empty headers tab showed blank content instead of empty state message
+- Email analytics crashed with `Cannot read properties of undefined (reading 'substring')` due to missing `email_id` in `TrackingEventResponse`
+- External URL in platform settings accepted invalid values with `#` or `?` characters; now validated on both client and server
 - Email tracking open/click endpoints returned 500 (`RequestMetadata` extension not found) because public routes lacked the middleware; now gracefully falls back to extracting IP/UA from headers
 - Email tracking events failed with `column "link_url" does not exist` on databases where the column was missing; added migration to backfill
 - Database connections could accumulate without recycling due to missing `idle_timeout` on the connection pool; now defaults to 10 minutes

crates/temps-config/src/handler.rs

@@ -333,6 +333,27 @@ async fn update_settings(
         }
     }
 
+    // Validate and sanitize external_url
+    if let Some(ref mut ext_url) = settings.external_url {
+        *ext_url = ext_url.trim().to_string();
+        *ext_url = ext_url.trim_end_matches('/').to_string();
+        if !ext_url.starts_with("http://") && !ext_url.starts_with("https://") {
+            return Err(ErrorBuilder::new(StatusCode::BAD_REQUEST)
+                .detail("External URL must start with http:// or https://")
+                .build());
+        }
+        if ext_url.contains('#') || ext_url.contains('?') {
+            return Err(ErrorBuilder::new(StatusCode::BAD_REQUEST)
+                .detail("External URL must not contain '#' or '?' characters")
+                .build());
+        }
+        if url::Url::parse(ext_url).is_err() {
+            return Err(ErrorBuilder::new(StatusCode::BAD_REQUEST)
+                .detail("External URL is not a valid URL")
+                .build());
+        }
+    }
+
     match app_state.config_service.update_settings(settings).await {
         Ok(_) => {
             let audit = SettingsUpdatedAudit {

crates/temps-email/src/handlers/mod.rs

@@ -57,6 +57,8 @@ pub fn configure_public_routes() -> Router<Arc<AppState>> {
         // Tracking
         tracking::track_open,
         tracking::track_click,
+        tracking::get_global_event_stats,
+        tracking::get_global_events,
         tracking::get_email_tracking,
         tracking::get_email_events,
         tracking::get_email_links,
@@ -90,6 +92,8 @@ pub fn configure_public_routes() -> Router<Arc<AppState>> {
             tracking::EmailTrackingResponse,
             tracking::TrackedLinkResponse,
             tracking::TrackingEventResponse,
+            tracking::GlobalEventStatsResponse,
+            tracking::PaginatedEventsResponse,
             // Validation types
             validation::ValidateEmailRequest,
             validation::ValidateEmailResponse,

crates/temps-email/src/handlers/tracking.rs

@@ -63,6 +63,8 @@ pub fn public_routes() -> Router<Arc<AppState>> {
 /// Configure authenticated tracking data routes
 pub fn routes() -> Router<Arc<AppState>> {
     Router::new()
+        .route("/emails/events/stats", get(get_global_event_stats))
+        .route("/emails/events", get(get_global_events))
         .route("/emails/{id}/tracking", get(get_email_tracking))
         .route("/emails/{id}/tracking/events", get(get_email_events))
         .route("/emails/{id}/tracking/links", get(get_email_links))
@@ -168,6 +170,140 @@ pub async fn track_click(
     }
 }
 
+// ============================================================
+// GLOBAL TRACKING ENDPOINTS
+// ============================================================
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct GlobalEventStatsResponse {
+    pub delivered: u64,
+    pub opened: u64,
+    pub clicked: u64,
+    pub bounced: u64,
+    pub complained: u64,
+    pub open_rate: Option<f64>,
+    pub click_rate: Option<f64>,
+    pub bounce_rate: Option<f64>,
+}
+
+#[derive(Debug, Serialize, ToSchema)]
+pub struct PaginatedEventsResponse {
+    pub events: Vec<TrackingEventResponse>,
+    pub total: u64,
+    pub page: u64,
+    pub page_size: u64,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct GlobalEventsQuery {
+    pub event_type: Option<String>,
+    pub page: Option<u64>,
+    pub page_size: Option<u64>,
+}
+
+/// GET /emails/events/stats
+#[utoipa::path(
+    tag = "Email Tracking",
+    get,
+    path = "/emails/events/stats",
+    responses(
+        (status = 200, description = "Global tracking statistics", body = GlobalEventStatsResponse),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("bearer_auth" = []))
+)]
+pub async fn get_global_event_stats(
+    RequireAuth(auth): RequireAuth,
+    State(state): State<Arc<AppState>>,
+) -> Result<impl IntoResponse, Problem> {
+    permission_guard!(auth, EmailsRead);
+
+    let stats = state
+        .tracking_service
+        .get_global_stats()
+        .await
+        .map_err(|e| {
+            error!("Failed to get global tracking stats: {}", e);
+            internal_server_error()
+                .detail("Failed to get tracking statistics")
+                .build()
+        })?;
+
+    Ok(Json(GlobalEventStatsResponse {
+        delivered: stats.delivered,
+        opened: stats.opened,
+        clicked: stats.clicked,
+        bounced: stats.bounced,
+        complained: stats.complained,
+        open_rate: stats.open_rate,
+        click_rate: stats.click_rate,
+        bounce_rate: stats.bounce_rate,
+    }))
+}
+
+/// GET /emails/events
+#[utoipa::path(
+    tag = "Email Tracking",
+    get,
+    path = "/emails/events",
+    params(
+        ("event_type" = Option<String>, Query, description = "Filter by event type (open, click)"),
+        ("page" = Option<u64>, Query, description = "Page number (default: 1)"),
+        ("page_size" = Option<u64>, Query, description = "Page size (default: 20, max: 100)"),
+    ),
+    responses(
+        (status = 200, description = "Paginated tracking events", body = PaginatedEventsResponse),
+        (status = 401, description = "Unauthorized"),
+    ),
+    security(("bearer_auth" = []))
+)]
+pub async fn get_global_events(
+    RequireAuth(auth): RequireAuth,
+    State(state): State<Arc<AppState>>,
+    Query(query): Query<GlobalEventsQuery>,
+) -> Result<impl IntoResponse, Problem> {
+    permission_guard!(auth, EmailsRead);
+
+    let page = query.page.unwrap_or(1);
+    let page_size = std::cmp::min(query.page_size.unwrap_or(20), 100);
+
+    let (events, total) = state
+        .tracking_service
+        .get_all_events(query.event_type.as_deref(), page, page_size)
+        .await
+        .map_err(|e| {
+            error!("Failed to get global events: {}", e);
+            internal_server_error()
+                .detail("Failed to get tracking events")
+                .build()
+        })?;
+
+    let response = PaginatedEventsResponse {
+        events: events
+            .into_iter()
+            .map(|e| TrackingEventResponse {
+                id: e.id,
+                email_id: e.email_id.to_string(),
+                event_type: e.event_type,
+                link_url: e.link_url,
+                link_index: e.link_index,
+                ip_address: e.ip_address,
+                user_agent: e.user_agent,
+                created_at: e.created_at.to_rfc3339(),
+            })
+            .collect(),
+        total,
+        page,
+        page_size,
+    };
+
+    Ok(Json(response))
+}
+
+// ============================================================
+// PER-EMAIL TRACKING ENDPOINTS
+// ============================================================
+
 /// Email tracking summary
 #[derive(Debug, Serialize, ToSchema)]
 pub struct EmailTrackingResponse {
@@ -195,6 +331,7 @@ pub struct TrackedLinkResponse {
 #[derive(Debug, Serialize, ToSchema)]
 pub struct TrackingEventResponse {
     pub id: i64,
+    pub email_id: String,
     pub event_type: String,
     pub link_url: Option<String>,
     pub link_index: Option<i32>,
@@ -337,6 +474,7 @@ pub async fn get_email_events(
         .into_iter()
         .map(|e| TrackingEventResponse {
             id: e.id,
+            email_id: e.email_id.to_string(),
             event_type: e.event_type,
             link_url: e.link_url,
             link_index: e.link_index,

crates/temps-email/src/services/tracking_service.rs

@@ -37,6 +37,19 @@ pub struct ExtractedLink {
     pub original_url: String,
 }
 
+/// Global tracking statistics
+#[derive(Debug, Clone)]
+pub struct GlobalTrackingStats {
+    pub delivered: u64,
+    pub opened: u64,
+    pub clicked: u64,
+    pub bounced: u64,
+    pub complained: u64,
+    pub open_rate: Option<f64>,
+    pub click_rate: Option<f64>,
+    pub bounce_rate: Option<f64>,
+}
+
 /// Event recorded for tracking
 #[derive(Debug, Clone)]
 pub struct TrackingEvent {
@@ -339,6 +352,93 @@ impl TrackingService {
         Ok(events)
     }
 
+    /// Get global tracking stats (aggregated from emails table)
+    pub async fn get_global_stats(&self) -> Result<GlobalTrackingStats, EmailError> {
+        use sea_orm::{DatabaseBackend, FromQueryResult, Statement};
+
+        #[derive(FromQueryResult)]
+        struct StatsRow {
+            total_sent: i64,
+            total_opens: i64,
+            total_clicks: i64,
+            emails_with_opens: i64,
+            emails_with_clicks: i64,
+        }
+
+        let sql = r#"
+            SELECT
+                COUNT(*) FILTER (WHERE status = 'sent') AS total_sent,
+                COALESCE(SUM(open_count), 0) AS total_opens,
+                COALESCE(SUM(click_count), 0) AS total_clicks,
+                COUNT(*) FILTER (WHERE open_count > 0) AS emails_with_opens,
+                COUNT(*) FILTER (WHERE click_count > 0) AS emails_with_clicks
+            FROM emails
+            WHERE track_opens = true OR track_clicks = true
+        "#;
+
+        let row = StatsRow::find_by_statement(Statement::from_string(
+            DatabaseBackend::Postgres,
+            sql.to_string(),
+        ))
+        .one(self.db.as_ref())
+        .await?
+        .unwrap_or(StatsRow {
+            total_sent: 0,
+            total_opens: 0,
+            total_clicks: 0,
+            emails_with_opens: 0,
+            emails_with_clicks: 0,
+        });
+
+        let delivered = row.total_sent;
+        let open_rate = if delivered > 0 {
+            Some(row.emails_with_opens as f64 / delivered as f64 * 100.0)
+        } else {
+            None
+        };
+        let click_rate = if delivered > 0 {
+            Some(row.emails_with_clicks as f64 / delivered as f64 * 100.0)
+        } else {
+            None
+        };
+
+        Ok(GlobalTrackingStats {
+            delivered: delivered as u64,
+            opened: row.total_opens as u64,
+            clicked: row.total_clicks as u64,
+            bounced: 0,
+            complained: 0,
+            open_rate,
+            click_rate,
+            bounce_rate: Some(0.0),
+        })
+    }
+
+    /// Get all tracking events across all emails (paginated)
+    pub async fn get_all_events(
+        &self,
+        event_type: Option<&str>,
+        page: u64,
+        page_size: u64,
+    ) -> Result<(Vec<email_events::Model>, u64), EmailError> {
+        use sea_orm::PaginatorTrait;
+
+        let mut query = email_events::Entity::find();
+
+        if let Some(et) = event_type {
+            query = query.filter(email_events::Column::EventType.eq(et));
+        }
+
+        let paginator = query
+            .order_by_desc(email_events::Column::Id)
+            .paginate(self.db.as_ref(), page_size);
+
+        let total = paginator.num_items().await?;
+        let events = paginator.fetch_page(page.saturating_sub(1)).await?;
+
+        Ok((events, total))
+    }
+
     /// Get tracked links for an email
     pub async fn get_links(&self, email_id: Uuid) -> Result<Vec<email_links::Model>, EmailError> {
         let links = email_links::Entity::find()