synheart-sensor-agent 0.2.2

//! # Synheart Sensor Agent
//!
//! **Privacy-first PC background sensor for behavioral research.**
//!
//! This library captures keyboard and mouse interaction timing for behavioral
//! research with strong privacy guarantees. Raw events are never stored — only
//! derived statistical features are produced as HSI 1.0 JSON snapshots.
//!
//! # Privacy Guarantees
//!
//! - **No key content** — only timing and category (typing vs. navigation)
//! - **No coordinates** — only mouse movement magnitude/speed
//! - **No raw storage** — events are discarded after feature extraction (every 10 s)
//! - **Transparency** — all collection is logged and auditable via [`TransparencyLog`]
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │                    Synheart Sensor Agent                    │
//! ├─────────────────────────────────────────────────────────────┤
//! │  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐        │
//! │  │  Collector  │──▶│  Windowing  │──▶│  Features   │        │
//! │  │ (platform)  │   │  (10s bins) │   │ (compute)   │        │
//! │  └─────────────┘   └─────────────┘   └─────────────┘        │
//! │         │                                    │              │
//! │         ▼                                    ▼              │
//! │  ┌─────────────┐                     ┌─────────────┐        │
//! │  │Transparency │                     │    HSI      │        │
//! │  │    Log      │                     │  Snapshot   │        │
//! │  └─────────────┘                     └─────────────┘        │
//! └─────────────────────────────────────────────────────────────┘
//! ```
//!
//! # Quick Start
//!
//! ```no_run
//! use synheart_sensor_agent::{collector, core, transparency};
//!
//! // Create a collector (requires Input Monitoring permission on macOS)
//! let config = collector::CollectorConfig::default();
//! let mut collector = collector::Collector::new(config);
//!
//! // Start collection
//! collector.start().expect("Failed to start collector");
//!
//! // Events can be received from collector.receiver()
//! ```
//!
//! # Modules
//!
//! | Module | Purpose |
//! |--------|---------|
//! | [`collector`] | Platform-specific event capture ([`SensorEvent`], [`Collector`]) |
//! | [`config`] | Agent configuration and persistence ([`Config`], [`SourceConfig`]) |
//! | [`core`] | Windowing, feature extraction, and HSI encoding ([`WindowManager`], [`compute_features`], [`HsiBuilder`]) |
//! | [`transparency`] | Auditable collection logging ([`TransparencyLog`], [`TransparencyStats`]) |
//! | [`flux`] | Synheart Flux integration for baseline tracking *(requires `flux` feature)* |
//! | [`gateway`] | Gateway client for real-time HSI sync *(requires `gateway` feature)* |
//! | [`server`] | HTTP server for Chrome extension ingest *(requires `server` feature)* |
//!
//! # Feature Flags
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `flux` | Enables [`SensorFluxProcessor`] for rolling baseline tracking via synheart-flux |
//! | `gateway` | Enables [`GatewayClient`] / [`BlockingGatewayClient`] for syncing HSI to the local gateway |
//! | `server` | Enables the HTTP ingest server for Chrome extension data (implies `flux` + `gateway`) |
//!
//! # Platform Support
//!
//! The [`collector`] module adapts to the build target:
//!
//! - **macOS** — CoreGraphics event tap + NSWorkspace for foreground app detection
//! - **Windows** — Windows Hooks API for keyboard/mouse + foreground window detection
//! - **Other** — No-op collector (compiles but does not capture events)

#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(missing_docs)]

/// Platform-specific event collection (keyboard, mouse, shortcuts).
///
/// See [`SensorEvent`](collector::types::SensorEvent) for the event types and
/// [`Collector`](collector::Collector) for the platform-agnostic entry point.
pub mod collector;

/// Agent configuration and persistence.
pub mod config;

/// Core functionality — windowing, feature extraction, and HSI snapshot building.
pub mod core;

/// Transparency logging for auditable data collection.
pub mod transparency;

/// Synheart Flux integration for baseline tracking and HSI enrichment.
///
/// See [`SensorFluxProcessor`](flux::SensorFluxProcessor) for the main entry point.
#[cfg(feature = "flux")]
pub mod flux;

/// Gateway client for syncing HSI snapshots to the local synheart-core-gateway.
///
/// See [`GatewayClient`](gateway::GatewayClient) for async usage and
/// [`BlockingGatewayClient`](gateway::BlockingGatewayClient) for synchronous usage.
#[cfg(feature = "gateway")]
pub mod gateway;

/// HTTP server for receiving behavioral data from the Chrome extension.
///
/// See `server::run` to start the server and `server::ServerConfig`
/// for configuration.
#[cfg(feature = "server")]
pub mod server;

// Re-export key types at crate root for convenience
pub use collector::{Collector, CollectorConfig, CollectorError, SensorEvent};
pub use config::{Config, SourceConfig};
pub use core::{compute_features, HsiBuilder, HsiSnapshot, WindowFeatures, WindowManager};
pub use transparency::{SharedTransparencyLog, TransparencyLog, TransparencyStats};

// Flux re-exports (when enabled)
#[cfg(feature = "flux")]
pub use flux::{EnrichedSnapshot, SensorFluxProcessor};

// Gateway re-exports (when enabled)
#[cfg(feature = "gateway")]
pub use gateway::{
    BlockingGatewayClient, GatewayClient, GatewayConfig, GatewayError, GatewayResponse,
};

// Server re-exports (when enabled)
#[cfg(feature = "server")]
pub use server::{run as run_server, ServerConfig};

/// Library version string sourced from `Cargo.toml`.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// Privacy declaration that can be displayed to users.
pub const PRIVACY_DECLARATION: &str = r#"
╔══════════════════════════════════════════════════════════════════╗
║           SYNHEART SENSOR AGENT - PRIVACY DECLARATION            ║
╠══════════════════════════════════════════════════════════════════╣
║                                                                  ║
║  This agent captures behavioral timing data for research.        ║
║                                                                  ║
║  ✓ WHAT WE CAPTURE:                                              ║
║    • When keys are pressed (timing only)                         ║
║    • Key categories (backspace, enter, etc. - NOT which letter)  ║
║    • Common shortcut patterns (copy, paste, etc. - timing only)  ║
║    • How fast the mouse moves (speed only)                       ║
║    • When clicks and scrolls occur (timing only)                 ║
║    • Which app is in the foreground (identifier only, no titles) ║
║                                                                  ║
║  ✗ WHAT WE NEVER CAPTURE:                                        ║
║    • Which keys you press (no passwords, messages, etc.)         ║
║    • Where your cursor is (no screen position tracking)          ║
║    • Window titles, file names, or document content              ║
║    • Any screen content                                          ║
║                                                                  ║
║  All data is processed locally. Raw events are discarded         ║
║  after feature extraction (every 10 seconds).                    ║
║                                                                  ║
║  You can view collection statistics anytime with:                ║
║    synheart-sensor status                                        ║
║                                                                  ║
╚══════════════════════════════════════════════════════════════════╝
"#;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_privacy_declaration_contents() {
        assert!(PRIVACY_DECLARATION.contains("PRIVACY"));
        assert!(PRIVACY_DECLARATION.contains("NEVER CAPTURE"));
        assert!(PRIVACY_DECLARATION.contains("keys you press"));
    }
}