<div align="center">
# ๐ฆ rusteero
**Async Rust client for the Eero mesh Wi-Fi cloud API**
[](https://www.rust-lang.org)
[](LICENSE)
---
_`rusteero` is a Rust client library for the Eero (Amazon) mesh Wi-Fi cloud API._
_It is a port of the Python [`eero-api`](https://github.com/fulviofreitas/eero-api) library at **v8.4.1**: same raw JSON contract, same method names, same credential record._
[Status](#-status) ยท [Quick Start](#-quick-start) ยท [Docs](#-docs) ยท [Acknowledgments](#-acknowledgments) ยท [License](#-license)
</div>
---
## โก Why rusteero?
- ๐ **Async-first** โ `tokio` + `reqwest` (rustls), no Python runtime
- ๐ฆ **Raw JSON** โ every call returns the exact `{meta, data}` envelope Eero sends, wrapped in a lossless `Envelope`
- ๐ **Link-aware** โ every resource argument accepts a bare id, an API path or an absolute API-host URL, and domain methods take a `parent` envelope wherever the Python method accepts one (`parent=`, or a cached envelope in place of the id), so the request follows the link the API published
- ๐ **Secure** โ session tokens are `SecretString`s sent only to the configured API origin (scheme, host and port), redirects are refused, error messages never embed a response body, and the transport's warning/error log lines never carry a request path or query (the withheld-credential warning names only the target's `scheme://host`)
- ๐ **Compatible** โ the `{"session_id", "schema_version": 2}` credential record is shared with `eero-api`, so a login made by [`eeroctl`](https://github.com/fulviofreitas/eeroctl) works unchanged (legacy records are migrated on first load)
- ๐งฉ **Headless-friendly** โ the email/SMS code step is separable; inject a pre-obtained token instead
## ๐ง Status
**Ported to `eero-api` 8.4.1.** Transport, authentication, verified credential storage, the error
catalogue, link resolution and path confinement, per-call timeouts, all 37 domain modules, the
`Client` facade and its cache are in place, each pinned by wiremock tests. [`PARITY.md`](PARITY.md)
is the method-by-method table against the Python library at tag `v8.4.1`: every row carries its
status (ported, changed, dropped, identical or renamed), every change or drop carries its reason,
and the summary line near the top of that file gives the totals per status.
## ๐ฆ Install
```toml
[dependencies]
rusteero = "3"
# Headless / embedded (no system keyring):
rusteero = { version = "3", default-features = false }
```
## ๐ Quick Start
### Build a `Client`
```rust
use rusteero::{Client, Session};
#[tokio::main]
async fn main() -> Result<(), rusteero::Error> {
// Headless: a token you already hold (e.g. from a previous login, or from eeroctl).
let session = Session::from_env("RUSTEERO_SESSION_TOKEN")?;
// Or interactively (once): email or phone -> one-time code -> Session.
// use rusteero::auth::flow::LoginFlow;
// let pending = LoginFlow::new(None)?.start("you@example.com").await?;
// let session = pending.verify(code.trim()).await?; // consumes `pending`
let client = Client::builder().session(Some(session)).build().await?;
// A cached read: `false` = serve from the 60 s cache when fresh.
let networks = client.get_networks(false).await?;
for n in networks.data()["networks"].as_array().into_iter().flatten() {
println!("๐ถ {}: {}", n["name"], n["status"]);
}
Ok(())
}
```
`ClientBuilder::build()` is `async` because it may load a session from a configured
credential store. A `Client` persists nothing unless you attach one โ the system keyring
(default `keyring` feature) uses the *same* entry the Python library does. See
[Configuration](https://github.com/fulviofreitas/rusteero/wiki/Configuration).
### A write: read, compare, skip
Writes are only issued after a read shows the value actually differs. Most writes have not been
characterised against a live network and log one `WARNING` before the request; a
settings-class write such as `set_sqm` may reboot the whole mesh.
```rust
use serde_json::json;
let current = client.get_sqm_settings(None).await?; // whole network object
if current.data()["sqm"] != json!(true) {
client.set_sqm(true, None).await?; // PUT ?sqm=true to the settings link
}
```
### Ids, paths, URLs and `parent`
Wherever a method takes a `network_id`, `eero_id`, `device_id` or `profile_id`, you may pass a
bare id, the resource's API path (`/2.2/networks/<id>`) or its absolute URL on the API host;
anything on another host, scheme or port, carrying userinfo, or naming a different kind of
resource than the method expects is rejected with `Error::Validation` before a request is sent.
Every domain-module method (`client.api().networks()`, โฆ) whose Python counterpart has `parent=`
also takes `parent: Option<&Value>` โ the envelope you already hold โ and resolves its URL from
the link the API published on it (as do `update_forward`, `update_reservation`, `update_schedule`
and `delete_schedule`, whose Python versions take the item's envelope in place of its id);
`Client` passes its cached network, eero and device envelopes as `parent` automatically.
### Error handling
```rust
use rusteero::{Error, ErrorGroup, classify_error_code};
match client.get_network(None, false).await {
Ok(env) => println!("{}", env.data()),
Err(Error::Authentication { error_code, .. }) => {
// Terminal: session expired / invalid / revoked. Re-seed a token or re-run LoginFlow.
eprintln!("re-login needed: {error_code:?}");
}
Err(Error::PremiumRequired { .. }) => eprintln!("needs Eero Plus"),
Err(Error::RateLimit { retry_after, status, .. }) => eprintln!("back off ({status:?}): {retry_after:?}"),
Err(e) => {
// Branch on the catalogue string, never on the message text.
if classify_error_code(e.error_code()) == Some(ErrorGroup::Domain) {
eprintln!("domain error {:?}: {:?}", e.error_code(), e.envelope());
}
return Err(e);
}
}
```
`Error::error_code()` is `meta.error` as the API sent it; `Error::envelope()` is the raw parsed
response; `Error::status()` the HTTP status when a response produced the error (`Authentication`
and `RateLimit` included, a server-side `Validation` excepted; `retry_after` is capped at 24
hours). Messages never embed a response body; a `Network` error's text includes the request URL
and a refused redirect's names the path and the `Location` host.
## ๐ Raw Response Format
All API methods return the exact JSON from Eero's API, wrapped in a lossless `Envelope`:
```json
{
"meta": { "code": 200, "server_time": "..." },
"data": { "...": "endpoint-specific payload" }
}
```
`env.meta()`, `env.data()`, `env.as_value()`, `env.into_value()` and `env.data_as::<T>()` are the
accessors; `Envelope::from_value`, `Envelope::empty` and `From<Value>` build one.
## ๐๏ธ Features
| `keyring` | on | Enables `KeyringStore`, backed by the OS keyring (macOS Keychain, Secret Service, Windows Credential Manager) |
## ๐ Docs
| **[๐ Rust API](../../wiki/Rust-API)** | Layers, builder options, every domain accessor, caching, errors |
| **[โ๏ธ Configuration](../../wiki/Configuration)** | Sessions, credential stores, transport options, logging |
| **[๐ง Troubleshooting](../../wiki/Troubleshooting)** | 401s, premium gating, validation errors, writes that change nothing |
| **[๐ Migration](../../wiki/Migration)** | Upgrading from rusteero 2.x (and from 1.0.0) |
| **[๐ Wiki Home](../../wiki)** | All documentation |
| **[โ
Parity checklist](PARITY.md)** | Method-by-method status against `eero-api` |
## ๐ Ecosystem
| **[๐ eero-api](https://github.com/fulviofreitas/eero-api)** | The Python library this crate is a port of |
| **[๐ฅ๏ธ eeroctl](https://github.com/fulviofreitas/eeroctl)** | Terminal interface for Eero networks (Python) |
| **[๐ eero-ui](https://github.com/fulviofreitas/eero-ui)** | Svelte dashboard for network management |
| **[๐ eero-prometheus-exporter](https://github.com/fulviofreitas/eero-prometheus-exporter)** | Prometheus metrics for monitoring |
## ๐ Acknowledgments
`rusteero` is a Rust client library for the Eero (Amazon) mesh Wi-Fi cloud API, ported from
[eero-api](https://github.com/fulviofreitas/eero-api). No code was copied from it or from any
other project; full lineage and licence attribution is in [NOTICE](NOTICE), and the long-form
version with what changed in the port is on the
[wiki](https://github.com/fulviofreitas/rusteero/wiki).
## โ ๏ธ Important Notes
> **Unofficial Project**: This library uses reverse-engineered APIs and is not affiliated with or endorsed by Eero or Amazon.
> **Amazon Login Limitation**: If your Eero account uses Amazon for login, this library may not work directly due to API limitations. **Workaround**: Have someone in your household create a standard Eero account (with email/password) and invite them as an admin to your network. Then use those credentials to authenticate.
## ๐ License
[MIT](LICENSE) โ Use it, fork it, build cool stuff ๐