rusteero 3.0.1

Async Rust client for the Eero (Amazon) mesh Wi-Fi cloud API โ€” a port of the Python eero-api library
Documentation

๐Ÿฆ€ rusteero

Async Rust client for the Eero mesh Wi-Fi cloud API

Rust 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 library at v8.4.1: same raw JSON contract, same method names, same credential record.

Status ยท Quick Start ยท Docs ยท Acknowledgments ยท License


โšก 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 SecretStrings 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 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 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

[dependencies]
rusteero = "3"

# Headless / embedded (no system keyring):
rusteero = { version = "3", default-features = false }

๐Ÿš€ Quick Start

Build a Client

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.

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.

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

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:

{
  "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

Feature Default Effect
keyring on Enables KeyringStore, backed by the OS keyring (macOS Keychain, Secret Service, Windows Credential Manager)

๐Ÿ“š Docs

Guide What's inside
๐Ÿ“– Rust API Layers, builder options, every domain accessor, caching, errors
โš™๏ธ Configuration Sessions, credential stores, transport options, logging
๐Ÿ”ง Troubleshooting 401s, premium gating, validation errors, writes that change nothing
๐Ÿ”€ Migration Upgrading from rusteero 2.x (and from 1.0.0)
๐Ÿ  Wiki Home All documentation
โœ… Parity checklist Method-by-method status against eero-api

๐Ÿ”— Ecosystem

Project Description
๐Ÿ eero-api The Python library this crate is a port of
๐Ÿ–ฅ๏ธ eeroctl Terminal interface for Eero networks (Python)
๐Ÿ›œ eero-ui Svelte dashboard for network management
๐Ÿ“Š 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. No code was copied from it or from any other project; full lineage and licence attribution is in NOTICE, and the long-form version with what changed in the port is on the 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 โ€” Use it, fork it, build cool stuff ๐ŸŽ‰