neuroclient/lib.rs
1//! # `NeuroClient`
2//!
3//! An independent Rust client for the
4//! [Emotiv Cortex v2 WebSocket API](https://emotiv.gitbook.io/cortex-api/).
5//!
6//! This crate provides a complete, typed interface to the Emotiv Cortex service
7//! for interacting with Emotiv EEG headsets (Insight, EPOC+, EPOC X, EPOC Flex).
8//! `NeuroClient` is not affiliated with, sponsored by, or endorsed by Emotiv.
9//!
10//! ## Quick Start
11//!
12//! ```no_run
13//! use neuroclient::{CortexClient, CortexConfig};
14//! use neuroclient::protocol::headset::QueryHeadsetsOptions;
15//!
16//! #[tokio::main]
17//! async fn main() -> neuroclient::CortexResult<()> {
18//! // Load config from environment or cortex.toml
19//! let config = CortexConfig::discover(None)?;
20//!
21//! // Connect to the Cortex service
22//! let mut client = CortexClient::connect(&config).await?;
23//!
24//! // Check service info
25//! let info = client.get_cortex_info().await?;
26//! println!("Cortex version: {:?}", info);
27//!
28//! // Authenticate
29//! let _token = client.authenticate(&config.client_id, &config.client_secret).await?;
30//!
31//! // Discover headsets
32//! let headsets = client.query_headsets(QueryHeadsetsOptions::default()).await?;
33//! for h in &headsets {
34//! println!("Found: {} ({})", h.id, h.status);
35//! }
36//!
37//! client.disconnect().await?;
38//! Ok(())
39//! }
40//! ```
41//!
42//! ## Two-Layer API
43//!
44//! | Layer | Type | Token mgmt | Reconnect | Retry | Best for |
45//! |-------|------|-----------|-----------|-------|----------|
46//! | Low-level | [`CortexClient`] | Manual | No | No | Examples, testing, full control |
47//! | High-level | `ResilientClient` | Automatic | Yes | Yes | Production applications |
48//!
49//! ## Configuration
50//!
51//! See [`CortexConfig`] for the full configuration reference.
52//! The simplest setup uses environment variables:
53//!
54//! ```bash
55//! export EMOTIV_CLIENT_ID="your-client-id"
56//! export EMOTIV_CLIENT_SECRET="your-client-secret"
57//! ```
58//!
59//! Or a `cortex.toml` file:
60//!
61//! ```toml
62//! client_id = "your-client-id"
63//! client_secret = "your-client-secret"
64//! ```
65//!
66//! ## Feature Flags
67//!
68//! TLS backend selection is explicit:
69//! - `rustls-tls` (default)
70//! - `native-tls`
71//!
72//! Exactly one TLS backend feature must be enabled.
73//! `config-toml` (default) controls TOML parsing support in [`CortexConfig`];
74//! when disabled, file-based config loading returns [`CortexError::ConfigError`].
75//!
76//! ## Protocol Modules
77//!
78//! Protocol types are grouped by domain:
79//! - `protocol::rpc`
80//! - `protocol::constants`
81//! - `protocol::headset`
82//! - `protocol::session`
83//! - `protocol::streams`
84//! - `protocol::records`
85//! - `protocol::profiles`
86//! - `protocol::training`
87//! - `protocol::auth`
88//! - `protocol::subjects`
89
90#[cfg(all(not(feature = "rustls-tls"), not(feature = "native-tls")))]
91compile_error!(
92 "neuroclient requires exactly one TLS backend feature: enable `rustls-tls` or `native-tls`."
93);
94
95#[cfg(all(feature = "rustls-tls", feature = "native-tls"))]
96compile_error!(
97 "neuroclient requires exactly one TLS backend feature: `rustls-tls` and `native-tls` are mutually exclusive."
98);
99
100pub mod client;
101pub mod config;
102pub mod error;
103pub mod headset;
104pub mod health;
105pub mod protocol;
106pub mod reconnect;
107pub mod retry;
108pub mod streams;
109
110// ─── Public re-exports ──────────────────────────────────────────────────
111
112pub use client::CortexClient;
113pub use config::CortexConfig;
114pub use error::{CortexError, CortexResult};
115pub use headset::HeadsetModel;
116pub use reconnect::ResilientClient;
117pub use streams::TypedStream;