Skip to main content

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;